Peekaboo
installs/mo · npmstarsforks
How to install Peekaboo?
openclaw/peekaboo
$git clone https://github.com/openclaw/PeekabooPeekaboo 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.
README.md
| 1 | # Peekaboo 🫣 - Mac automation that sees the screen and does the clicks. |
| 2 | |
| 3 |  |
| 4 | |
| 5 | [](https://www.npmjs.com/package/@steipete/peekaboo) |
| 6 | [](https://opensource.org/licenses/MIT) |
| 7 | [-0078d7?logo=apple&logoColor=white&style=flat-square)](https://www.apple.com/macos/) |
| 8 | [](https://swift.org/) |
| 9 | [](https://nodejs.org/) |
| 10 | [](https://github.com/openclaw/Peekaboo/releases/latest) |
| 11 | [](https://github.com/steipete/homebrew-tap) |
| 12 | [](https://deepwiki.com/openclaw/Peekaboo) |
| 13 | |
| 14 | 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. |
| 15 | |
| 16 | ## What you get |
| 17 | - Pixel-accurate captures (windows, screens, menu bar) with optional Retina 2x scaling. |
| 18 | - Natural-language agent that chains Peekaboo tools (see, click, type, scroll, hotkey, menu, window, app, dock, space). |
| 19 | - Action-first UI automation for routine clicks/scrolls, with background process-targeted input by default when a target is known. |
| 20 | - Direct accessibility tools for settable values and named actions (`set-value`, `perform-action`). |
| 21 | - Menu and menubar discovery with structured JSON; no clicks required. |
| 22 | - Multi-provider AI through Tachikoma, including hosted, local, and OpenAI-/Anthropic-compatible providers. |
| 23 | - Claude Fable 5 support with 1M context and a 128K output ceiling; saved temperature/max-token settings are shared by the app and CLI and clamped to each model's capabilities. |
| 24 | - MCP server for Codex, Claude Code, and Cursor plus a native CLI; the same tools in both. |
| 25 | - Warm daemon and Peekaboo.app Bridge hosts for permission-bound automation, with distinct lease-owned sockets and local fallback. |
| 26 | - Configurable, testable workflows with reproducible sessions and strict typing. |
| 27 | - Requires macOS Screen Recording + Accessibility permissions (see [docs/permissions.md](docs/permissions.md)). |
| 28 | |
| 29 | ## Install |
| 30 | - macOS app + CLI (Homebrew): |
| 31 | ```bash |
| 32 | brew install steipete/tap/peekaboo |
| 33 | ``` |
| 34 | - MCP server (Node 22+, no global install needed): |
| 35 | ```bash |
| 36 | npx -y @steipete/peekaboo |
| 37 | ``` |
| 38 | |
| 39 | ### Important for 3.9.6 upgrades |
| 40 | |
| 41 | Peekaboo 3.9.6 completes the move from Peter Steinberger's Developer ID team to the OpenClaw Foundation identity for every shipped macOS executable. macOS treats the new CLI signature as a different TCC client, so **re-grant Screen Recording, Accessibility, and any Automation access you use after updating**. Open Peekaboo.app's Permissions onboarding or run `peekaboo permissions grant`; see [Permissions & Performance](docs/permissions.md) for the exact System Settings panes. |
| 42 | |
| 43 | ## Quick start |
| 44 | ```bash |
| 45 | # Capture full screen at Retina scale and save to Desktop |
| 46 | peekaboo image --mode screen --retina --path ~/Desktop/screen.png |
| 47 | |
| 48 | # Capture current UI state, then copy its snapshot and opaque element IDs exactly |
| 49 | peekaboo see --app Safari --json |
| 50 | SNAPSHOT="<snapshot-id>" |
| 51 | TEXT_FIELD_ID="<text-field-id>" |
| 52 | BUTTON_ID="<button-id>" |
| 53 | |
| 54 | # Click a button by label |
| 55 | peekaboo click --on "Reload this page" --snapshot "$SNAPSHOT" |
| 56 | |
| 57 | # Directly set a text field value when the accessibility value is settable |
| 58 | peekaboo set-value --on "$TEXT_FIELD_ID" --value "hello" --snapshot "$ |
People who liked this also viewed
6 picksType
- fastmcp🚀 The fast, Pythonic way to build MCP servers and clients.MCP ServersJul 2026
- playwright-mcpPlaywright MCP serverMCP ServersJul 2026
- ext-appsOfficial repo for spec & SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP serversMCP ServersJul 2026
- langchain-mcp-adaptersLangChain 🔌 MCPMCP ServersJul 2026
- mcporterCall MCPs via TypeScript, masquerading as simple TypeScript API. Or package them as cli.MCP ServersJul 2026
- mcp-proxyA bridge between Streamable HTTP and stdio MCP transportsMCP ServersJul 2026
