Peekaboo

Peekaboo 🫣 — Mac automation that sees the screen and does the clicks.

[](https://github.com/openclaw/Peekaboo/actions/workflows/macos-ci.yml) [](https://www.npmjs.com/package/@steipete/peekaboo) [](https://github.com/openclaw/Peekaboo/releases/latest) [](docs/platform-support.md) [](https://swift.org/) [](https://nodejs.org/) [](LICENSE) [](https://github.com/openclaw/homebrew-tap) [](https://deepwiki.com/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

brew install openclaw/tap/peekaboo

MCP package with npm

The npm package requires Node.js 22 or later and includes the CLI plus its MCP launcher.

npx -y @steipete/peekaboo --version

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:

peekaboo permissions status
peekaboo see --no-elements --mode screen --path /tmp/peekaboo-screen.png

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:

peekaboo see --app Finder --json

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.6

Peekaboo 4.9.6 is a fix release. Apps that re-exec themselves on launch, such as Xcode's Device Hub, are no longer invisible: AppKit reports their PID as -1, and Peekaboo now recovers the one verified live process so they can be listed, inspected and captured. window close reports success when an app keeps its closed window alive or quits, the Mac app's saved Vision model is used for image analysis, and the Mac chat keeps Stop attached across follow-ups, records each prompt and reply once, keeps the menu bar in sync and opens the recent session you clicked.

Automate an app

List Safari's windows, copy the intended window_id (12345 below), then keep the entire interaction pinned to

that exact window:

peekaboo window list --app Safari --json
peekaboo click "Address and search bar" --app Safari --window-id 12345
peekaboo type "github.com/openclaw/Peekaboo" --app Safari --window-id 12345
peekaboo press Return --app Safari --window-id 12345

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:

peekaboo agent "Open Safari, go to github.com, and search for Peekaboo" --allow-foreground

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 ↗ ·

· Control macOS · app, window, menu, menubar, dock, dialog, space · Command reference ↗ ·

· Run workflows · agent, capture · Agent ↗ · Capture ↗ ·

· Integrate with clients · mcp, browser, tools · MCP ↗ ·

Run peekaboo help <command> for live CLI help. The complete command index ↗ links to flags, examples, and troubleshooting for every command.

Configuration

Peekaboo stores provider credentials and settings under ~/.peekaboo. Use peekaboo config to inspect or change them, and consult the configuration guide ↗ for profiles, environment variables, and custom providers. The provider reference ↗ covers hosted, compatible, and local model backends.

Shell completions for zsh, bash, and fish come from peekaboo completions; see the completion guide ↗ for persistent setup.

Learn more

• Project direction ↗
• Platform support ↗
• Architecture ↗
• Building from source ↗
• Testing ↗
• Agent chat loop ↗
• Command reference ↗

Community

• PeekabooWin ↗ — Windows-first rewrite of the Peekaboo automation loop (JavaScript + PowerShell) by @FelixKruger ↗
• PeekabooX ↗ — Linux-first rewrite of the Peekaboo automation loop (Rust + Python) by @nordbyte ↗

Development

Source builds require macOS 15 or later, Swift 6.2 or later, Node.js 22 or later, and the repository's submodules.

pnpm install --frozen-lockfile
pnpm run build:cli
pnpm run lint:docs
pnpm run test:safe

More build, signing, and test details live in docs/building.md ↗.

License

MIT. See LICENSE ↗.