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.
The released CLI and app require macOS 15 or later.
brew install steipete/tap/peekabooThe npm package requires Node.js 22 or later and includes the CLI plus its MCP launcher.
npx -y @steipete/peekaboo --versionSee MCP setup to connect it to Codex, Claude Code, Cursor, or another MCP client.
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.
Check the permissions available to Peekaboo, then take a screenshot:
peekaboo permissions status
peekaboo image --mode screen --path /tmp/peekaboo-screen.pngScreen 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 --jsonThat is the core loop: observe the current screen, choose an element from the result, and act on it.
Target an element by its accessible label, then send text to the same app:
peekaboo click "Address and search bar" --app Safari
peekaboo type "github.com/openclaw/Peekaboo" --app Safari --returnTargeted input uses background delivery when Peekaboo can resolve the process, so the app does not have to become frontmost. Add --foreground when an app only accepts input in its focused key window. See the automation guide for element IDs, coordinates, snapshots, waits, and input behavior.
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"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.
| Goal | Commands | Guide |
|---|---|---|
| Observe the desktop | image, see, list, screen |
Capture and inspection |
| Interact with UI | click, type, press, scroll, drag, set-value, perform-action |
Automation |
| Control macOS | app, window, menu, menubar, dock, dialog, space |
Command reference |
| Run workflows | agent, run |
Agent · Scripts |
| 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.
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.
- Project direction
- Platform support
- Architecture
- Building from source
- Testing
- Agent chat loop
- Service API
- 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
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:safeMore build, signing, and test details live in docs/building.md.
MIT. See LICENSE.