Peekaboo

# Peekaboo 🫣 - Mac automation that sees the screen and does the clicks.  [](https://www.npmjs.com/package/@steipete/peekaboo) [](https://opensource.org/licenses/MIT) [-0078d7?logo=apple&logoColor=white&style=flat-square)](https://www.apple.com/macos/) [](https://swift.org/) [](https://nodejs.org/) [](https://github.com/steipete/peekaboo/releases/latest) [](https://github.com/steipete/homebrew-tap) [](https://deepwiki.com/steipete/peekaboo) Peekaboo brings high-fidelity screen capture, AI analysis, and complete GUI automation to macOS. Version 3 adds native agent flows and multi-screen automation across the CLI and MCP server. > Note: v3 is currently in beta (3.0.0-beta1) and has a few known issues; see the changelog for details. ## What you get - Pixel-accurate captures (windows, screens, menu bar) with optional Retina 2x scaling. - Natural-language agent that chains Peekaboo tools (see, click, type, scroll, hotkey, menu, window, app, dock, space). - Menu and menubar discovery with structured JSON; no clicks required. - Multi-provider AI: GPT-5.1 family, Claude 4.x, Grok 4-fast (vision), Gemini 2.5, and local Ollama models. - MCP server for Claude Desktop and Cursor plus a native CLI; the same tools in both. - Configurable, testable workflows with reproducible sessions and strict typing. - Requires macOS Screen Recording + Accessibility permissions (see [docs/permissions.md](docs/permissions.md)). ## Install - macOS app + CLI (Homebrew): ```bash brew install steipete/tap/peekaboo ``` - MCP server (Node 22+, no global install needed): ```bash npx -y @steipete/peekaboo ``` ## Quick start ```bash # Capture full screen at Retina scale and save to Desktop peekaboo image --mode screen --retina --path ~/Desktop/screen.png # Click a button by label (captures, resolves, and clicks in one go) peekaboo see --app Safari --json-output | jq -r '.data.session_id' | read SID peekaboo click --on "Reload this page" --session "$SID" # Run a natural-language automation peekaboo "Open Notes and create a TODO list with three items" # Run as an MCP server (Claude/Cursor) npx -y @steipete/peekaboo # Minimal Claude Desktop config snippet (Developer → Edit Config): # { # "mcpServers": { # "peekaboo": { # "command": "npx", # "args": ["-y", "@steipete/peekaboo"], # "env": { # "PEEKABOO_AI_PROVIDERS": "openai/gpt-5.1,anthropic/claude-opus-4" # } # } # } # } ``` | Command | Key flags / subcommands | What it does | | --- | --- | --- | | [see](docs/commands/see.md) | `--app`, `--mode screen/window`, `--retina`, `--json-output` | Capture and annotate UI, return session + element IDs | | [click](docs/commands/click.md) | `--on <id/query>`, `--session`, `--wait`, coords | Click by element ID, label, or coordinates | | [type](docs/commands/type.md) | `--text`, `--clear`, `--delay-ms` | Enter text with pacing options | | [press](docs/commands/press.md) | key names, `--repeat` | Special keys and sequences | | [hotkey](docs/commands/hotkey.md) | combos like `cmd,shift,t` | Modifier combos (cmd/ctrl/alt/shift) | | [scroll](docs/commands/scroll.md) | `--on <id>`, `--direction up/down`, `--ticks` | Scroll views or elements | | [swipe](docs/commands/swipe.md) | `--from/--to`, `--duration`, `--steps` | Smooth gesture-style drags | | [drag](docs/commands/drag.md) | `--from/--to`, modifiers, Dock/Trash targets | Drag-and-drop between elements/coords | | [move](docs/commands/move.md) | `--to <id/coords>`, `--screen-index` | Position the cursor without clicking | | [window](docs/commands/window.md) | `list`, `move`, `resize`, `focus`, `set-bounds` | Move/resize/focus windows and Spaces | | [app](docs/commands/app.md) | `launch`, `quit`, `relaunch`, `switch`, `list` | Launch, quit, relaunch, switch apps | | [space](docs/commands/space.md) | `list`, `switch`, `move-window` | List or switch macOS Spaces | | [menu](docs/commands/menu.md) | `list`, `list-all`, `click`, `click-extra` | List/click app menus and extras | | [menubar](docs/commands/menubar.md) | `list`, `click` | Target status-bar items by name/index | | [dock](docs/commands/dock.md) | `lau