# 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
```sh
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.
```sh
npx -y @steipete/peekaboo --version
```
See [MCP setup](docs/MCP.md) to connect it to Codex, Claude Code, Cursor, or another MCP client.
### Mac app
Download the signed DMG from the [latest GitHub release](https://github.com/openclaw/Peekaboo/releases/latest). 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](docs/install.md).
## Quick start
Check the permissions available to Peekaboo, then take a screenshot:
```sh
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](docs/permissions.md) covers setup and the additional permission used for synthetic input.
Inspect a running app to get a structured UI map with opaque element IDs:
```sh
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.8
Peekaboo 4.9.8 is a fix release. `dialog file` can now select a file in an Open panel, going through Go to Folder and checking the selection before it confirms, and it no longer types filenames into Search. Exact-window clicks and `window focus` keep working when another running app shares the target's name, `see` and `window list` find windows that an app exposes only through its focused or main window, `window focus` falls back to Accessibility when macOS declines activation, and MCP starts when another Peekaboo process owns the capture lane without a Bridge.
## Automate an app
List Safari's windows, copy the intended `window_id` (`12345` below), then keep the entire interaction pinned to
that exact window:
```sh
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](docs/automation.md) 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:
```sh
peekaboo agent "Open Safari, go to github.com, and search for Peekaboo" --allow-foreground
```
Agent runs need a configured model provider. See [agent setup](docs/commands/agent.md) for providers and sessions, or [MCP setup](docs/MCP.md) to expose Peekaboo's tools to another client.
## Command map
| Goal | Commands | Guide |
| --- | --- | --- |
| Observe the desktop | `see`, `screen list`, `window list` | [Capture and inspection](docs/quickstart.md) |
| Interact with UI | `click`, `type`, `press`, `scroll`, `drag`, `set-value`, `action` | [Automation](docs/automation.md) |
| Control macOS | `app`, `window`, `menu`, `menubar`, `dock`, `dialog`, `space` | [Command reference](docs/commands/README.md) |
| Run workflows | `agent`, `capture` | [Agent](docs/commands/agent.md) · [Capture](docs/commands/capture.md) |
| Integrate with clients | `mcp`, `browser`, `tools` | [MCP](docs/MCP.md) |
Run `peekaboo help <command>` for live CLI help. The [complete command index](docs/commands/README.md) 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](docs/configuration.md) for profiles, environment variables, and custom providers. The [provider reference](docs/providers.md) covers hosted, compatible, and local model backends.
Shell completions for zsh, bash, and fish come from `peekaboo completions`; see the [completion guide](docs/commands/completions.md) for persistent setup.
## Learn more
- [Project direction](VISION.md)
- [Platform support](docs/platform-support.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Building from source](docs/building.md)
- [Testing](docs/testing/tools.md)
- [Agent chat loop](docs/agent-chat.md)
- [Command reference](docs/cli-command-reference.md)
## Community
- [PeekabooWin](https://github.com/FelixKruger/PeekabooWin) — Windows-first rewrite of the Peekaboo automation loop (JavaScript + PowerShell) by [@FelixKruger](https://github.com/FelixKruger)
- [PeekabooX](https://github.com/nordbyte/PeekabooX) — Linux-first rewrite of the Peekaboo automation loop (Rust + Python) by [@nordbyte](https://github.com/nordbyte)
## Development
Source builds require macOS 15 or later, Swift 6.2 or later, Node.js 22 or later, and the repository's submodules.
```sh
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](docs/building.md).
## License
MIT. See [LICENSE](LICENSE).