Peekaboo pins Mac automation to a window id and an app

Three install paths, and the binary is not always the same one

Peekaboo ships three things under one name: a macOS CLI, a menu-bar app, and an MCP server that exposes the same toolset to other clients. The released CLI and the app require macOS 15 or later. Homebrew installs straight from the project's own tap:

brew install openclaw/tap/peekaboo

The npm route needs Node.js 22 or later and carries the CLI plus its MCP launcher, so a version query is the quickest way to confirm what landed:

npx -y @steipete/peekaboo --version

The third route is the signed DMG on the latest GitHub release. That app is where permission onboarding, visual feedback and agent sessions live, and it does not put the binary on PATH, so install the CLI separately when you want `peekaboo` in a shell. Before automating anything, check the grants, capture the screen, and ask for a structured map of one app:

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

The `--json` flag on that last command matters more than it looks. It is what turns a screenshot into something an agent can reason about, and it is the subject of the next section.

Opaque element ids are the price of a JSON UI map

The observe step is one command with two faces. `see --mode screen` writes an image, and `see --app Finder --json` writes a structured UI map built from Accessibility data, where every control comes back with an opaque element id. The loop the project describes is deliberately short: look at the current screen, choose an element from the result, act on it. Opaque ids are what that map costs you. Nothing in the documentation promises an id survives a relaunch or a resize, so a script that hardcodes one has an expiry date, and the fix is to re-run `see` and re-resolve rather than to retry with the same value. Permissions gate the two faces separately. Screen capture needs Screen Recording. UI inspection and control need Accessibility, and the permissions guide covers an additional permission used for synthetic input, so a run that types and clicks is exercising three grants rather than one. `peekaboo permissions status` is the command that tells you which ones you actually hold.

Window ids are what keep a click off the wrong window

Once you have a target, the next decision is which window the action belongs to. Listing windows as JSON gives you the id, and every later command can carry it:

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 input is delivered in the background when Peekaboo can resolve the process, so the target app never has to become frontmost and your keystrokes do not land in whatever was focused before. Raw `press` chords can also stay in the background if you supply an exact window selector. Drop that selector and the rules change: app or PID alone, and targetless chords, require explicit foreground consent, and window selector only chords need it too when they arrive through Agent or MCP. The CLI accepts a fresh exact non dialog snapshot, and that snapshot is what the background only Agent and MCP policy requires. The advice to prefer a semantic action such as `menu click` when one exists is practical: a menu item is a stable target, an element id resolved two minutes ago is not.

The Bridge host version decides which 4.8.0 actions exist at all

Peekaboo 4.9.7 is a fix release: `window close` through the daemon now reports success when an app keeps its closed window alive, `see` works on Chrome windows whose titles carry the app name or are elided, `window close --foreground` handles apps that re-exec themselves, and `dock list` hides separators. The releases land close together: v4.9.7 on 2026-10-23, v4.9.6 on 2026-10-20 and v4.9.5 on 2026-10-17, with the last push on 2026-10-27. A release every few days means a CLI pinned in a lockfile and an app someone dragged off the release page drift apart within days. An upgrade is therefore a two part operation, and comparing the version on both sides is the only cheap way to see the mismatch.

Agent runs need a provider under ~/.peekaboo before they touch the screen

The agent command plans a natural language run out of the same observation and action tools, and it needs a model before it can do anything:

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

Agent runs need a configured model provider. The agent setup guide covers providers and sessions, and the provider reference separates hosted, compatible and local backends, so the same loop can run against a service or against something on your own machine. Settings and provider credentials are stored under `~/.peekaboo`, and `peekaboo config` is how you inspect or change them. Two consequences follow for a reader. On a fresh install, `agent` stops at the provider step, and the flag that carries real weight is `--allow-foreground`, the explicit consent that targetless work demands. And the README does not say how those credentials are protected at rest, so treat `~/.peekaboo` as a secrets directory and check its permissions before pointing the tool at a hosted backend. Picking a local model changes where prompts and screenshots travel, not the permission list.

The npm payload is two entry points and a compatibility dylib

Installing through npm gives you a package that doubles as an MCP server, and its manifest shows how small the shipped payload is:

"bin": {
  "peekaboo": "peekaboo",
  "peekaboo-mcp": "peekaboo-mcp.js"
},
"files": [
  "peekaboo",
  "libswiftCompatibility*.dylib",
  "peekaboo-mcp.js",
  "README.md",
  "LICENSE"
]

That version is 4.9.7, the entry point is `peekaboo-mcp.js`, and the two commands placed on PATH are `peekaboo` and `peekaboo-mcp`. The `libswiftCompatibility*.dylib` file is a Swift compatibility library that travels with the binary. Integration work sits under `mcp`, `browser` and `tools` in the command map, and the MCP setup guide shows how to hand the same toolset to Codex, Claude Code, Cursor or another client. The practical effect is that one machine can hold two different Peekaboo builds at once, a Homebrew copy on PATH and a cached copy inside an agent client. Nothing in the package synchronises them. When behaviour differs between your shell and your MCP client, compare versions on both before hunting for a bug in the tool.

macOS 15 and Swift 6.2 set the floor, and the other two platforms are community rewrites

Source builds have a hard floor: macOS 15 or later, Swift 6.2 or later, Node.js 22 or later, and the repository submodules that `.gitmodules` exists to pull in. The build sequence is short:

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

`build:cli` calls a Python workspace helper before invoking `swift build` against `Apps/CLI`, and `test:safe` is a long chain covering the Swift workspace, log scripts, ambient state policy, the MCP wrapper, guidance, the CodeQL build graph, release validation and the docs. Sibling scripts build an arm only binary or a universal one, and a restart script installs the companion app with a deployment flag. Accessibility inspection and synthetic input are macOS facilities, so portability does not live in this repository. Two community projects carry the same loop elsewhere: PeekabooWin, a Windows first rewrite in JavaScript and PowerShell by @FelixKruger, and PeekabooX, a Linux first rewrite in Rust and Python by @nordbyte. Different languages, different automation APIs, no shared release train. A team with Linux CI cannot reuse these scripts, and docs/platform-support.md is the file to read before assuming coverage.

The CLI surface documents waits, but it documents no rollback

The repository is much larger than the tool. The top level holds `Apps/`, `Core/`, `Helpers/`, `Commander/`, `AXorcist/`, `Swiftdansi/`, `Tachikoma/`, `TauTUI/`, alongside `experiments/`, `skills/`, `tests/`, `homebrew/`, `appcast.xml` and `version.json`. What reaches a user is much smaller: two binaries, one MCP entry point, a compatibility dylib and a README. The distance between those two lists is where the friction lives. The README names no rollback for an action that landed on the wrong element, and it lists no dry run or undo flag for the same reason. It also does not state how long a command waits before giving up, and that single missing number decides whether your agent retries a click once or wanders into a second window. The questions are answered elsewhere, though: docs/automation.md covers element ids, coordinates, snapshots, waits and input behaviour, docs/commands/README.md is the complete command index, and `peekaboo help <command>` returns live help for the binary you actually have installed. Plan recovery around a fresh `see` and a re pinned window id instead of an undo, and treat the agent command as the step that needs a human review afterwards, because `--allow-foreground` hands it the keyboard.

Editorial conclusion

Adopt Peekaboo if your work already lives on macOS 15 or later and you want screen capture, UI inspection and native clicking in one CLI that an agent can call. Skip it for a cross platform pipeline, because the only Windows and Linux implementations are community rewrites in other languages. Before you commit, run `peekaboo permissions status` and `peekaboo --version` on the exact machine, confirm the app on that machine is the same version as the CLI, and read docs/automation.md, which is where waits and input behaviour are actually documented.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes