Peekaboo: Tự Động Hóa macOS Bằng AI

Peekaboo Là Gì?

Peekaboo là một CLI macOS và app menu-bar tùy chọn dùng để chụp màn hình, kiểm tra accessibility, và tự động hóa UI native, kèm một MCP server đưa cùng bộ công cụ đó cho các AI client như Codex, Claude Code, hay Cursor. Nó quan sát màn hình hoặc một app đang chạy qua `peekaboo see`, lệnh này trả về các phần tử UI kèm ID ẩn, rồi để bạn hoặc một agent thao tác trên chúng bằng các lệnh như `click`, `type`, và `press`.

Khả Năng Cốt Lõi

• ✓Chụp màn hình và chụp app qua `peekaboo see`, có thể nhắm vào toàn màn hình hoặc một app cụ thể, ghi ra file PNG cùng một bản đồ UI có cấu trúc trừ khi bạn truyền `--no-elements`.
• ✓Kiểm tra UI có cấu trúc: `peekaboo see --app Finder --json` trả về các phần tử kèm ID ẩn để bạn tham chiếu ở lệnh sau, thay vì phải đoán tọa độ pixel.
• ✓Các lệnh tự động hóa UI native — `click`, `type`, `press`, `scroll`, `drag`, `set-value`, `action` — nhắm vào một phần tử qua nhãn accessible của nó.
• ✓Gửi input nền: các lệnh nhắm mục tiêu có thể tới một app không ở trạng thái frontmost khi Peekaboo xác định được process của nó, kèm cờ `--foreground` cho app chỉ nhận input khi đang ở cửa sổ focus.
• ✓Lệnh `agent` nhận một câu lệnh ngôn ngữ tự nhiên, ví dụ mở Safari và tìm kiếm trên một trang, rồi nối chuỗi các công cụ quan sát/hành động để thực hiện, dùng một model provider đã cấu hình.
• ✓Một MCP server (`peekaboo mcp`) phơi bày cùng bộ công cụ chụp/kiểm tra/thao tác cho các MCP client như Codex, Claude Code, hay Cursor.
• ✓Điều khiển ở cấp hệ thống ngoài UI của một app riêng lẻ — các lệnh `app`, `window`, `menu`, `menubar`, `dock`, `dialog`, `space`.
• ✓Từ bản 4.0, bề mặt lệnh gốc cố định đúng 33 lệnh với ngữ pháp duration và coordinate nhất quán, cùng cơ chế polling `verify` native để xác nhận hiệu ứng của một hành động.

Bắt Đầu Với Peekaboo

Bản CLI và app đã phát hành yêu cầu macOS 15 trở lên. Cài CLI bằng Homebrew: `brew install steipete/tap/peekaboo`. Với package MCP, dùng npm/npx với Node.js 22 trở lên: `npx -y @steipete/peekaboo --version`, package này gói cả CLI lẫn MCP launcher — xem tài liệu setup MCP để kết nối với Codex, Claude Code, Cursor, hay một MCP client khác. Bản app Mac là file DMG đã ký từ bản phát hành GitHub mới nhất; nó xử lý phần onboarding quyền, phản hồi trực quan, và các phiên agent, nhưng bạn vẫn cần cài CLI riêng nếu muốn có `peekaboo` trên PATH. Build từ source cần thêm Swift 6.2 trở lên, pnpm, và các submodule của repo, build bằng `pnpm install --frozen-lockfile` rồi `pnpm run build:cli`.

Tự Động Hóa Tác Vụ macOS

Bắt đầu với `peekaboo permissions status` để xác nhận Screen Recording và Accessibility đã được cấp, rồi chụp màn hình bằng `peekaboo see --no-elements --mode screen --path /tmp/peekaboo-screen.png`. Để kiểm tra một app đang chạy, `peekaboo see --app Finder --json` trả về một bản đồ UI có cấu trúc kèm ID phần tử ẩn — vòng lặp quan sát-rồi-hành-động đó chính là cốt lõi cách Peekaboo hoạt động. Để tự động hóa một app, nhắm vào một phần tử qua nhãn accessible của nó: `peekaboo click "Address and search bar" --app Safari`, rồi `peekaboo type "github.com/openclaw/Peekaboo" --app Safari && peekaboo press Return --app Safari`. Với các lượt chạy bằng ngôn ngữ tự nhiên, `peekaboo agent "Open Safari, go to github.com, and search for Peekaboo"` nối chuỗi cùng các công cụ đó, nhưng cần một model provider đã cấu hình trước.

Kịch Bản Tự Động Hóa Thực Tế

• •Kết nối một AI coding agent, như Claude Code, Cursor, hay Codex, để thực sự nhìn thấy và điều khiển một app macOS trong lúc thực hiện tác vụ, qua MCP server của Peekaboo thay vì AppleScript thô.
• •Script hoá một quy trình UI lặp lại, như mở Safari, gõ URL vào address bar, rồi nhấn Return, dùng `click`/`type`/`press` nhắm vào các nhãn accessible.
• •Chạy `peekaboo agent "<câu lệnh>"` khi tác vụ dễ mô tả bằng ngôn ngữ tự nhiên hơn là code cứng thành một script cố định.
• •Tự động hóa một app chạy nền mà không cướp focus cửa sổ, vì input nhắm mục tiêu dùng cơ chế gửi nền bất cứ khi nào Peekaboo xác định được process đích.
• •Đưa screenshot cho một model AI local hoặc remote để trả lời câu hỏi trực quan, theo đúng mô tả GitHub của dự án.

Các Công Cụ Tự Động Hóa macOS Khác

Câu Hỏi Thường Gặp

Vấn đề Peekaboo giải quyết

Các AI coding agent chỉ nhận được mô tả văn bản của một app macOS thì phải đoán tọa độ pixel hoặc dựa vào AppleScript viết tay cho từng thao tác UI. README của Peekaboo đóng khung mục đích của nó quanh khoảng trống đó: cho một agent, hoặc một script, lệnh `see` trả về các phần tử UI thật, có nhãn, kèm ID ẩn, rồi thao tác trên các phần tử đó qua Accessibility API thay vì tọa độ cứng hay code script riêng cho từng app.

Ai nên dùng — và ai nên bỏ qua

Hãy thử Peekaboo nếu bạn đang xây dựng hoặc script hoá automation cho macOS và muốn truy cập phần tử UI có cấu trúc thay vì tọa độ mù, đặc biệt nếu bạn đang kết nối một AI agent qua MCP để thực sự nhìn thấy và thao tác trên màn hình Mac. Bỏ qua nếu bạn cần automation đa nền tảng, vì bản thân Peekaboo chỉ dành cho macOS và trỏ sang dự án khác cho Windows hay Linux, hoặc nếu bạn chỉ cần chụp màn hình nhanh mà không muốn cấp quyền Screen Recording và Accessibility.

Repo liên quan