Install

Peekaboo ships in three flavors. They all use the same Swift core and the same toolset — pick whichever surface fits your workflow.

Homebrew (recommended)

The CLI is signed, notarized, and lives in steipete/homebrew-tap.

brew install steipete/tap/peekaboo
peekaboo --version

Update with brew upgrade steipete/tap/peekaboo.

npm (for MCP clients)

The npm package wraps the same CLI plus an MCP shim, so you can launch the server with npx:

npx -y @steipete/peekaboo mcp

This is the form you point Codex, Claude Code, and Cursor at. See MCP.md.

Mac app

The full menu-bar app (visualizer, permission flows, status item) ships as a drag-to-Applications DMG on the Releases page. The app and CLI are separate installs; use Homebrew or npm above when you also need the peekaboo command on your PATH.

Build from source

Requires macOS 15.0+ and a Swift 6.2+ toolchain. See platform-support.md for the support matrix across the CLI, app, Swift packages, and pnpm helper scripts.

git clone --recurse-submodules https://github.com/openclaw/Peekaboo.git
cd Peekaboo
pnpm install
pnpm run build:cli         # debug build
pnpm run build:swift:all   # universal release

The output binary lives under Apps/CLI/.build/.... See building.md for signing and notarization. Raw SwiftPM and manual unstamped Xcode builds use stable unknown placeholders for source and build-time metadata. Use the repository's debug or release build scripts from a clean checkout when peekaboo --version --json must include immutable provenance. Dirty or unverifiable debug builds remain available but report sourceCommit: unknown; release builds and debug builds with PEEKABOO_REQUIRE_SOURCE_PROVENANCE=1 refuse that source state. peekaboo --version --json exposes the canonical 40-hex sourceCommit; background certification requires it and pins one exact Bridge socket for remote execution, requiring that host to advertise the same source commit.

Verify

peekaboo --version
peekaboo permissions status
peekaboo app list

If any of those error out, jump to permissions.md.