Total Pageviews

Sunday, 15 November 2026

Peekaboo

 Peekaboo is a macOS CLI & optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.

 http://www.peekaboo.boo/

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

CI npm GitHub release macOS 15+ Swift 6.2 Node License Homebrew Ask DeepWiki

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.

Peekaboo banner

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

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

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.

from  https://github.com/openclaw/Peekaboo

 ---------------------------------------------------------

Install Peekaboo

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

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

brew install openclaw/tap/peekaboo
peekaboo --version

Update with brew upgrade openclaw/tap/peekaboo.

brew install peekaboo installs Homebrew core's source-built formula without release signing. Local in-process commands still work. For normal Bridge and daemon use, install the notarized CLI: install it with brew install openclaw/tap/peekaboo or npm i -g @steipete/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.

In Settings, Show Peekaboo in → Menu bar only keeps Peekaboo out of the Dock and Command-Tab, even while Settings, Inspector, or an enabled Sessions window is open. Use the menu-bar item or configured keyboard shortcuts to return to those windows. Menu bar and Dock keeps the Dock and Command-Tab entry available even after all windows are closed. Launch starts in accessory mode until the saved preference is connected, so Menu bar only never briefly promotes the app into the Dock.

An unattended background Bridge host stays out of the Dock and suppresses automatic window presentation regardless of the saved Dock preference. Explicitly opening a window from the menu bar or a shortcut resumes that preference for the running host; it does not force a Dock entry when Menu bar only is selected.

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

For local daemon development, set PEEKABOO_ALLOW_UNSIGNED_DAEMON=1 on both the unsigned CLI and daemon (CLI auto-start and daemon start propagate it). This permits only an on-demand daemon/client pair with the same effective UID and exact same live kernel CDHash. It does not enable unsigned GUI Bridge access, and release-signed binaries ignore it. Status labels the connection as unsigned same-binary developer opt-in. Ad-hoc builds lack the hardened runtime, so injected code can run under the same binary; enable only on machines you control. Prefer the notarized install. See unsigned developer builds for details.

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. Raw builds remain available for ordinary CLI development, but capture action is deliberately stricter because its manifest claims end-to-end artifact and execution-host provenance around an arbitrary child command. That subcommand requires either an Apple-anchored, source-stamped local executable or an authenticated selected Bridge host; an unstamped local build refuses before focus or child dispatch instead of publishing a non-certified manifest.

from  https://peekaboo.sh/install.html

No comments:

Post a Comment