Peekaboo

npm package License: MIT macOS 15.0+ (Sequoia) Swift 6.2 node >=22 Download macOS Homebrew Ask DeepWiki

Peekaboo brings high-fidelity screen capture, AI analysis, and complete GUI automation to macOS. Version 3 adds native agent flows and multi-screen automation across the CLI and MCP server.

What you get

• Pixel-accurate captures (windows, screens, menu bar) with optional Retina 2x scaling.
• Natural-language agent that chains Peekaboo tools (see, click, type, scroll, hotkey, menu, window, app, dock, space).
• Action-first UI automation for routine clicks/scrolls, with synthetic input fallback for apps that need it.
• Direct accessibility tools for settable values and named actions (set-value, perform-action).
• Menu and menubar discovery with structured JSON; no clicks required.
• Multi-provider AI through Tachikoma, including hosted, local, and OpenAI-/Anthropic-compatible providers.
• MCP server for Codex, Claude Code, and Cursor plus a native CLI; the same tools in both.
• Configurable, testable workflows with reproducible sessions and strict typing.
• Requires macOS Screen Recording + Accessibility permissions (see docs/permissions.md).

Install

• macOS app + CLI (Homebrew):

  brew install steipete/tap/peekaboo
  

• MCP server (Node 22+, no global install needed):

  npx -y @steipete/peekaboo
  

Quick start

# Capture full screen at Retina scale and save to Desktop
peekaboo image --mode screen --retina --path ~/Desktop/screen.png

# Click a button by label (captures, resolves, and clicks in one go)
peekaboo see --app Safari --json | jq -r '.data.snapshot_id' | read SNAPSHOT
peekaboo click --on "Reload this page" --snapshot "$SNAPSHOT"

# Directly set a text field value when the accessibility value is settable
peekaboo set-value --on T1 --value "hello" --snapshot "$SNAPSHOT"

# Invoke a named accessibility action on an element
peekaboo perform-action --on B1 --action AXPress --snapshot "$SNAPSHOT"

# Run a natural-language automation
peekaboo agent "Open Notes and create a TODO list with three items"

# Run as an MCP server (Codex, Claude Code, Cursor)
npx -y @steipete/peekaboo

# Minimal MCP client config snippet:
# {
#   "mcpServers": {
#     "peekaboo": {
#       "command": "npx",
#       "args": ["-y", "@steipete/peekaboo"],
#       "env": {
#         "PEEKABOO_AI_PROVIDERS": "openai/gpt-5.5,anthropic/claude-opus-4-7"
#       }
#     }
#   }
# }

Shell completions

Peekaboo can generate shell-native completions directly from the same Commander metadata that powers CLI help and docs:

# Current shell (recommended)
eval "$(peekaboo completions $SHELL)"

# Explicit shells
eval "$(peekaboo completions zsh)"
eval "$(peekaboo completions bash)"
peekaboo completions fish | source

For persistent setup and troubleshooting, see docs/commands/completions.md.

Command	Key flags / subcommands	What it does
see	--app, --mode screen/window, --retina, --json	Capture and annotate UI, return snapshot + element IDs
click	--on <id/query>, --snapshot, --wait-for, --coords	Click by element ID, label, or coordinates
type	--text, --clear, --profile, --delay	Enter text with pacing options
set-value	--on <id/query>, --value, --snapshot	Directly set a settable accessibility value
perform-action	--on <id/query>, --action, --snapshot	Invoke a named accessibility action
press	key names, --count, --delay, --hold	Special keys and sequences
hotkey	combos like cmd,shift,t	Modifier combos (cmd/ctrl/alt/shift)
scroll	--on <id>, --direction up/down, --amount	Scroll views or elements
swipe	--from/--to, --duration, --steps	Smooth gesture-style drags
drag	--from/--to, modifiers, Dock/Trash targets	Drag-and-drop between elements/coords
move	--to <id/coords>, --screen-index	Position the cursor without clicking
window	list, move, resize, focus, set-bounds	Move/resize/focus windows and Spaces
app	launch, quit, relaunch, switch, list	Launch, quit, relaunch, switch apps
space	list, switch, move-window	List or switch macOS Spaces
menu	list, list-all, click, click-extra	List/click app menus and extras
menubar	list, click	Target status-bar items by name/index
dock	launch, right-click, hide, show, list	Interact with Dock items
dialog	list, click, input, file, dismiss	Drive system dialogs (open/save/etc.)
image	--mode screen/window/menu, --retina, --analyze	Screenshot screen/window/menu bar (+analyze)
list	apps, windows, screens, menubar, permissions	Enumerate apps, windows, screens, permissions
tools	--verbose, --json, --no-sort	Inspect native Peekaboo tools
completions	[shell]	Generate zsh/bash/fish completion scripts from Commander metadata
config	init, show, add, login, models	Manage credentials/providers/settings
permissions	status, grant	Check/grant required macOS permissions
run	.peekaboo.json, --output, --no-fail-fast	Execute .peekaboo.json automation scripts
sleep	--duration (ms)	Millisecond delays between steps
clean	--all-snapshots, --older-than, --snapshot	Prune snapshots and caches
agent	--model, --dry-run, --resume, --max-steps, audio	Natural-language multi-step automation
mcp	serve (default)	Run Peekaboo as an MCP server

Models and providers

Peekaboo's provider list changes with Tachikoma and the tested model catalog. See docs/providers.md for the current provider reference, including OpenAI, Anthropic, xAI/Grok, Google Gemini, MiniMax, Ollama, LM Studio, and compatible custom endpoints.

Set providers via PEEKABOO_AI_PROVIDERS or peekaboo config add.

Learn more

• Command reference: docs/commands/
• Platform support: docs/platform-support.md
• Architecture: docs/ARCHITECTURE.md
• Building from source: docs/building.md
• Testing guide: docs/testing/tools.md
• MCP setup: docs/commands/mcp.md
• Permissions: docs/permissions.md
• Ollama/local models: docs/ollama.md
• Agent chat loop: docs/agent-chat.md
• Service API reference: docs/service-api-reference.md

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 basics

• Requirements: see docs/platform-support.md. Node 22+ is only needed for the npm MCP wrapper and pnpm helper scripts.
• Install deps: pnpm install then pnpm run build:cli or pnpm run test:safe.
• Lint/format: pnpm run lint && pnpm run format.

License

MIT