Peekaboo: Cho AI agent "đôi mắt" để quan sát và điều khiển giao diện macOS

Key takeaways:

Chụp ảnh màn hình không gián đoạn: Peekaboo sử dụng Apple ScreenCaptureKit để chụp cửa sổ mà không cần chuyển tiêu điểm (focus), không làm gián đoạn luồng làm việc của người dùng.

Visual Question Answering tích hợp: AI agent có thể đặt câu hỏi cụ thể về nội dung màn hình thay vì xử lý toàn bộ ảnh thô, tiết kiệm đáng kể không gian context window.

Hoạt động song song ở hai chế độ: Vừa là CLI độc lập (cài qua Homebrew), vừa là MCP server (cài qua npm) – cùng bộ công cụ, hai cách tích hợp khác nhau.

Hỗ trợ cả mô hình đám mây và cục bộ: Tương thích với OpenAI GPT-4o, Anthropic Claude, Google Gemini, Grok và các mô hình local qua Ollama (LLaVA, Qwen2-VL).

Kiến trúc tự động hóa GUI đầy đủ: Ngoài chụp ảnh, Peekaboo còn cung cấp click, nhập text, cuộn, kéo thả, phím tắt, quản lý cửa sổ và điều hướng menu – tất cả qua lệnh có thể soạn kịch bản.

Bài toán: AI agent gỡ lỗi trong bóng tối

Khi xây dựng các hệ thống AI tự động hóa trên macOS – kiểm thử giao diện, gỡ lỗi ứng dụng, hay điều phối luồng công việc phức tạp – một vấn đề cơ bản thường bị bỏ qua: AI agent không thể nhìn thấy màn hình. Mô hình ngôn ngữ có thể đọc log, phân tích code, và gọi công cụ, nhưng nếu một dialog xuất hiện, một lỗi hiển thị trên giao diện, hay trạng thái UI thay đổi ngoài dự kiến – agent hoàn toàn mù trước những sự kiện đó.

Peekaboo, được phát triển bởi Peter Steinberger, giải quyết đúng khoảng trống này. Đây là công cụ mã nguồn mở dành riêng cho macOS, kết hợp khả năng chụp ảnh màn hình độ nét cao, phân tích hình ảnh bằng AI (Visual Question Answering), và tự động hóa GUI hoàn chỉnh – tất cả có thể gọi từ dòng lệnh hoặc qua giao thức MCP (Model Context Protocol) để tích hợp trực tiếp vào các AI agent như Claude hay Cursor.

Kiến trúc cốt lõi của Peekaboo

Kết hợp Swift và TypeScript cho hiệu năng tối ưu

Điểm đặc biệt trong thiết kế Peekaboo là sự kết hợp có chủ đích giữa hai ngôn ngữ: Swift cho phần lõi capture và tự động hóa, TypeScript/Node.js cho lớp MCP server.

Phần Swift truy cập trực tiếp vào ScreenCaptureKit – API gốc của Apple cho phép chụp cửa sổ cụ thể mà không cần chuyển tiêu điểm sang ứng dụng đó. Đây là điểm then chốt: các giải pháp cũ dùng AppleScript bắt buộc phải mang ứng dụng lên foreground trước khi chụp, gây gián đoạn người dùng. ScreenCaptureKit truy cập thẳng vào window manager của hệ điều hành, loại bỏ hoàn toàn hạn chế này.

Phần TypeScript cung cấp lớp MCP server mỏng, dễ phân phối qua npm và tương thích với hệ sinh thái công cụ AI ngày càng mở rộng.

Vòng lặp capture – interpret – act

Peekaboo vận hành theo một vòng lặp ba bước rõ ràng:

See (quan sát): Chụp màn hình hoặc cửa sổ cụ thể, trả về bản đồ UI có cấu trúc kèm ID ổn định cho từng phần tử.
Decide (quyết định): Xác định mục tiêu hành động dựa trên nhãn phần tử, đường dẫn menu, hoặc vị trí tọa độ.
Do (thực thi): Click, nhập văn bản, cuộn, kéo thả, hoặc thực thi kịch bản tự động hóa hoàn chỉnh – với log xác nhận từng bước.

Vòng lặp này lặp lại liên tục cho đến khi tác vụ hoàn thành, cho phép agent tự điều chỉnh dựa trên kết quả quan sát thực tế thay vì chạy mù theo kịch bản cứng.

Các tính năng cốt lõi

Chụp ảnh màn hình độ nét cao

Lệnh image và see cung cấp hai cấp độ chụp:

image: Chụp ảnh thuần túy của toàn màn hình, cửa sổ cụ thể, hoặc thanh menu, với tùy chọn Retina 2x và flag --analyze để phân tích ngay.
see: Chụp ảnh và trả về thêm bản đồ UI có cấu trúc – danh sách các phần tử giao diện kèm ID ổn định để các lệnh tiếp theo có thể tham chiếu (--on <id>).

Visual Question Answering – hiệu quả hơn gửi ảnh thô

Thay vì đưa toàn bộ ảnh màn hình vào context của mô hình ngôn ngữ (tốn token và có thể vượt giới hạn), Peekaboo cho phép đặt câu hỏi cụ thể: “Nút Submit có hiển thị không?”, “Console đang báo lỗi gì?”, “Trường input đã được điền chưa?”. Mô hình vision xử lý ảnh và chỉ trả về câu trả lời ngắn gọn, giữ cho context window của agent gọn sạch.

Tính năng này hỗ trợ cả mô hình đám mây (GPT-4o, Claude, Gemini, Grok) và mô hình chạy hoàn toàn cục bộ qua Ollama (LLaVA, Qwen2-VL) – cho phép cân bằng giữa độ chính xác và quyền riêng tư dữ liệu.

Tự động hóa GUI toàn diện

Bên cạnh quan sát, Peekaboo cung cấp bộ công cụ tương tác đầy đủ:

Nhóm chức năng	Các lệnh	Mô tả ngắn
Tương tác chuột	`click`, `scroll`, `swipe`, `drag`, `move`	Click theo ID/nhãn/tọa độ, cuộn, kéo thả
Nhập liệu	`type`, `press`, `hotkey`	Nhập text, phím đặc biệt, tổ hợp phím
Điều hướng	`menu`, `menubar`, `dock`, `app`, `space`	Menu app, thanh trạng thái, Dock, macOS Spaces
Cửa sổ	`window`, `dialog`	Di chuyển, resize, focus cửa sổ; điều khiển hộp thoại hệ thống
Kịch bản	`run`, `agent`	Chạy file `.peekaboo.json`, tác vụ ngôn ngữ tự nhiên nhiều bước

Hướng dẫn cài đặt Peekaboo trên macOS

Yêu cầu hệ thống

macOS 15 (Sequoia) trở lên.
Với MCP server: Node.js 22+.
Với phân tích AI: API key từ nhà cung cấp mô hình, hoặc Ollama cho mô hình cục bộ.

Cách 1: Cài đặt CLI qua Homebrew (khuyến nghị)

# Thêm tap của tác giả và cài đặt
brew tap steipete/tap
brew install peekaboo

Sau khi cài đặt, kiểm tra xác nhận:

peekaboo --help

Cách 2: Cài đặt MCP server qua npm

# Cài đặt MCP server và chạy ngay
npx -y @steipete/peekaboo-mcp

Cấp quyền macOS bắt buộc

Peekaboo yêu cầu hai quyền hệ thống. Kiểm tra trạng thái hiện tại bằng:

peekaboo permissions status

Nếu chưa được cấp, mở hướng dẫn cấp quyền:

peekaboo permissions grant

Hai quyền cần thiết:

Screen Recording: Cho phép chụp nội dung cửa sổ ứng dụng (System Settings > Privacy & Security > Screen Recording).
Accessibility: Cho phép tương tác với phần tử UI (System Settings > Privacy & Security > Accessibility).

Cấu hình mô hình AI để phân tích ảnh

Khởi tạo file cấu hình và khai báo nhà cung cấp mô hình:

# Khởi tạo file cấu hình
peekaboo config init

# Xem và chỉnh sửa cấu hình
peekaboo config show

Thêm API key qua biến môi trường trong ~/.zshrc hoặc ~/.bash_profile:

# Cho OpenAI GPT-4o
export OPENAI_API_KEY="sk-..."

# Cho Anthropic Claude
export ANTHROPIC_API_KEY="your-key-here"

# Khai báo chuỗi provider ưu tiên (thử lần lượt từ trái sang phải)
export PEEKABOO_AI_PROVIDERS="openai/gpt-4o,ollama/llava:latest"

Với mô hình cục bộ qua Ollama:

# Cài mô hình LLaVA (cân bằng giữa chất lượng và tài nguyên)
ollama pull llava:latest

# Hoặc Qwen2-VL cho máy tính cấu hình thấp hơn
ollama pull qwen2-vl:7b

Hướng dẫn sử dụng CLI

Chụp ảnh và phân tích trực tiếp

# Chụp toàn màn hình
peekaboo image --mode screen

# Chụp cửa sổ của ứng dụng cụ thể (hỗ trợ fuzzy matching)
peekaboo image --app "Safari"

# Chụp và phân tích cùng lúc
peekaboo image --app "Safari" --analyze "Trang web này đang hiển thị gì?"

# Chụp với độ phân giải Retina 2x
peekaboo image --app "Xcode" --retina --analyze "Có lỗi nào trong console không?"

Quan sát và tương tác với phần tử UI

# Chụp và lấy bản đồ UI có ID phần tử
peekaboo see --app "MyApp"

# Click vào nút theo nhãn
peekaboo click --on "Submit"

# Nhập văn bản vào trường hiện tại
peekaboo type --text "[email protected]"

# Thực thi tổ hợp phím
peekaboo hotkey cmd,shift,t

Chạy tác vụ ngôn ngữ tự nhiên nhiều bước

# Peekaboo agent tự lập kế hoạch và thực thi
peekaboo agent "Mở Safari, điều hướng đến github.com, và tìm kiếm Peekaboo"

# Hoặc dùng one-liner rút gọn
peekaboo "Kiểm tra xem ứng dụng có đang hiển thị lỗi không và chụp màn hình lại"

Thiết lập MCP server cho AI agent

Tích hợp với Claude Desktop

Thêm cấu hình vào file ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": ["-y", "@steipete/peekaboo-mcp"],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "openai/gpt-4o,ollama/llava:latest",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Sau khi khởi động lại Claude Desktop, agent có thể gọi trực tiếp các công cụ: chụp màn hình, phân tích giao diện, và nhận câu trả lời về trạng thái hiển thị hiện tại.

Tích hợp với Cursor IDE

Cursor hỗ trợ cài đặt Peekaboo MCP qua một lệnh deeplink hoặc cấu hình thủ công trong ~/.cursor/mcp.json với cấu trúc tương tự Claude Desktop ở trên.

Ứng dụng thực tế

Gỡ lỗi tự trị trong CI/CD

Kịch bản điển hình: một test giao diện thất bại trong pipeline CI. Thay vì dừng lại và hỏi người dùng “bạn đang thấy gì?”, agent có thể:

Gọi peekaboo image --app "TestRunner" --analyze "Lỗi nào đang hiển thị?".
Nhận câu trả lời mô tả trạng thái UI hiện tại.
Tự chẩn đoán nguyên nhân và thực hiện bước sửa lỗi tiếp theo.
Lặp lại vòng lặp cho đến khi test pass.

Đây là nền tảng cho CI tự trị thực sự – agent không chỉ chạy lệnh mà còn quan sát và phản ứng với kết quả trực quan.

Kiểm thử hồi quy giao diện

Kết hợp peekaboo see với cơ chế lưu snapshot, các thay đổi giao diện không mong muốn có thể bị phát hiện tự động. Agent so sánh bản đồ UI qua các phiên bản, gắn cờ khi phần tử biến mất hoặc vị trí thay đổi.

Tự động hóa tác vụ lặp đi lặp lại

Với file .peekaboo.json định nghĩa chuỗi hành động, các quy trình lặp đi lặp lại như điền form, trích xuất dữ liệu từ ứng dụng desktop, hoặc điều phối nhiều ứng dụng cùng lúc có thể được soạn kịch bản và chạy không giám sát.

Peekaboo lấp đầy một khoảng trống thực sự trong hệ sinh thái AI agent trên macOS: khả năng quan sát và tương tác với giao diện đồ họa theo cách phi gián đoạn, có cấu trúc, và có thể tích hợp vào mọi luồng tự động hóa. Kiến trúc kép CLI/MCP, hỗ trợ mô hình đa nhà cung cấp, và triết lý thiết kế “ít công cụ nhưng mỗi công cụ phải rất mạnh” làm cho Peekaboo trở thành lựa chọn đáng xem xét nghiêm túc khi xây dựng hệ thống tự động hóa thế hệ tiếp theo trên Mac.

Duy Nghiện

Hãy làm khán giả, đừng làm nhân vật chính :)