openclaw/Peekaboo

Peekaboo is a macOS CLI and menu-bar app for screen capture, accessibility inspection, and native UI automation. Use it directly, let its agent plan multi-step work, or expose the same toolset to MCP clients.
Install
The released CLI and app require macOS 15 or later.
CLI with Homebrew
MCP package with npm
The npm package requires Node.js 22 or later and includes the CLI plus its MCP launcher.
See MCP setup to connect it to Codex, Claude Code, Cursor, or another MCP client.
Mac app
Download the signed DMG from the latest GitHub release. The menu-bar app provides permission onboarding, visual feedback, and agent sessions; install the CLI separately when you also need peekaboo on PATH.
For source builds and alternative install details, see the installation guide.
Quick start
Check the permissions available to Peekaboo, then take a screenshot:
Screen capture requires Screen Recording permission. Accessibility permission enables UI inspection and control; the permissions guide covers setup and the additional permission used for synthetic input.
Inspect a running app to get a structured UI map with opaque element IDs:
That is the core loop: observe the current screen, choose an element from the result, and act on it.
What's new in 4.9.4
Peekaboo 4.9.4 is a fix release. While a granted Peekaboo.app is running, commands no longer drop to the permissions of an on-demand daemon started from an ungranted terminal, permission guidance names macOS 27's renamed "Device Control and Data Access" Settings row, and an unsigned source build such as Homebrew core's peekaboo formula now explains why Bridge and daemon hosts reject it and points to the notarized install. See the changelog for details.
Automate an app
List Safari's windows, copy the intended window_id (12345 below), then keep the entire interaction pinned to
that exact window:
Targeted semantic and typed CLI input uses background delivery when Peekaboo can resolve the process, so the app does
not have to become frontmost. Raw CLI press chords can also stay background with an exact window selector. The CLI
also accepts a fresh exact non-dialog snapshot; that snapshot is required by background-only Agent/MCP policy.
App/PID-only and targetless chords require explicit foreground consent, as do window-selector-only Agent/MCP chords.
Prefer a semantic action such as menu click when one exists. See the
automation guide for element IDs, coordinates, snapshots, waits, and input behavior.
Agent and MCP
The agent combines the same observation and action tools into a natural-language run:
Agent runs need a configured model provider. See agent setup for providers and sessions, or MCP setup to expose Peekaboo's tools to another client.
Command map
| Goal | Commands | Guide |
| --- | --- | --- |
| Observe the desktop | see, screen list, window list | Capture and inspection |
| Interact with UI | click, type, press, scroll, drag, set-value, action | Automation |