promisingcoder Peekaboo
Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI
elements, drive input, and manage apps/windows/menus. Commands share a snapshot
cache and support --json/-j for scripting. Run peekaboo or
peekaboo <cmd> --help for flags; peekaboo --version prints build metadata.
Tip: run via polter peekaboo to ensure fresh builds.
MarketingClaw Bridge
The MarketingClaw macOS app hosts Peekaboo Bridge at
~/Library/Application Support/MarketingClaw/bridge.sock. Before running Peekaboo
from MarketingClaw, select that socket so the CLI uses the app's Screen Recording
and Accessibility grants instead of starting its standalone daemon:
export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/MarketingClaw/bridge.sock}"
Confirm routing with peekaboo bridge status --json; hostKind must be gui
and the socket path must end in MarketingClaw/bridge.sock.
Features (all CLI capabilities, excluding agent/MCP)
Core
bridge: inspect Peekaboo Bridge host connectivitycapture: live capture or video ingest + frame extractionclean: prune snapshot cache and temp filesconfig: init/show/edit/validate, providers, models, credentialsimage: capture screenshots (screen/window/menu bar regions)learn: print the full agent guide + tool cataloglist: apps, windows, screens, menubar, permissionspermissions: check Screen Recording/Accessibility statusrun: execute.peekaboo.jsonscriptssleep: pause execution for a durationtools: list available tools with filtering/display options
Interaction
click: target by ID/query/coords with smart waitsdrag: drag & drop across elements/coords/Dockhotkey: modifier combos likecmd,shift,tmove: cursor positioning with optional smoothingpaste: set clipboard -> paste -> restorepress: special-key sequences with repeatsscroll: directional scrolling (targeted + smooth)swipe: gesture-style drags between targetstype: text + control keys (--clear, delays)
System
app: launch/quit/relaunch/hide/unhide/switch/list appsclipboard: read/write clipboard (text/images/files)dialog: click/input/file/dismiss/list system dialogsdock: launch/right-click/hide/show/list Dock itemsmenu: click/list application menus + menu extrasmenubar: list/click status bar itemsopen: enhancedopenwith app targeting + JSON payloadsspace: list/switch/move-window (Spaces)visualizer: exercise Peekaboo visual feedback animationswindow: close/minimize/maximize/move/resize/focus/list
Vision
see: annotated UI maps, snapshot IDs, optional analysis
Global runtime flags
--json/-j,--verbose/-v,--log-level <level>--no-remote,--bridge-socket <path>
Quickstart (happy path)
peekaboo permissions
peekaboo list apps --json
peekaboo see --annotate --path /tmp/peekaboo-see.png
peekaboo click --on B1
peekaboo type "Hello" --return
Common targeting parameters (most interaction commands)
- App/window:
--app,--pid,--window-title,--window-id,--window-index - Snapshot targeting:
--snapshot(ID fromsee; defaults to latest) - Element/coords:
--on/--id(element ID),--coords x,y - Focus control:
--no-auto-focus,--space-switch,--bring-to-current-space,--focus-timeout-seconds,--focus-retry-count
Common capture parameters
- Output:
--path,--format png|jpg,--retina - Targeting:
--mode screen|window|frontmost,--screen-index,--window-title,--window-id - Analysis:
--analyze "prompt",--annotate - Capture engine:
--capture-engine auto|classic|cg|modern|sckit
Common motion/typing parameters
- Timing:
--duration(drag/swipe),--steps,--delay(type/scroll/press) - Human-ish movement:
--profile human|linear,--wpm(typing) - Scroll:
--direction up|down|left|right,--amount <ticks>,--smooth
Examples
See -> click -> type (most reliable flow)
peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
peekaboo click --on B3 --app Safari
peekaboo type "user@example.com" --app Safari
peekaboo press tab --count 1 --app Safari
peekaboo type "supersecret" --app Safari --return
Target by window id
peekaboo list windows --app "Visual Studio Code" --json
peekaboo click --window-id 12345 --coords 120,160
peekaboo type "Hello from Peekaboo" --window-id 12345
Capture screenshots + analyze
peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"
Live capture (motion-aware)
peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
--active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture
App + window management
peekaboo app launch "Safari" --open https://example.com
peekaboo window focus --app Safari --window-title "Example"
peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
peekaboo app quit --app Safari
Menus, menubar, dock
peekaboo menu click --app Safari --item "New Window"
peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
peekaboo menu click-extra --title "WiFi"
peekaboo dock launch Safari
peekaboo menubar list --json
Mouse + gesture input
peekaboo move 500,300 --smooth
peekaboo drag --from B1 --to T2
peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
peekaboo scroll --direction down --amount 6 --smooth
Keyboard input
peekaboo hotkey --keys "cmd,shift,t"
peekaboo press escape
peekaboo type "Line 1\nLine 2" --delay 10
Notes
- Requires Screen Recording + Accessibility permissions.
- In MarketingClaw subprocesses, set
PEEKABOO_BRIDGE_SOCKETas shown above. Do not pass--no-remoteunless the calling process has its own Screen Recording grant. - Diagnose subprocess capture failures with
peekaboo bridge status --json, thenpeekaboo permissions status --json, then a normal Bridge-routed capture such aspeekaboo image --mode screen --json. - On macOS 15+, the "bypass private window picker" prompt is separate from the base Screen Recording grant; it can appear even when Bridge permissions are otherwise correct.
- Use
peekaboo see --annotateto identify targets before clicking.