/peekaboo

name: peekaboo
description: Capture and automate macOS UI with the Peekaboo CLI.
homepage: https://peekaboo.boo
metadata:
  {
    "openclaw":
      {
        "emoji": "👀",
        "os": ["darwin"],
        "requires": { "bins": ["peekaboo"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "steipete/tap/peekaboo",
              "bins": ["peekaboo"],
              "label": "Install Peekaboo (brew)",
            },
          ],
      },
  }

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.

Features (all CLI capabilities, excluding agent/MCP)

Core

• `bridge`: inspect Peekaboo Bridge host connectivity
• `capture`: live capture or video ingest + frame extraction
• `clean`: prune snapshot cache and temp files
• `config`: init/show/edit/validate, providers, models, credentials
• `image`: capture screenshots (screen/window/menu bar regions)
• `learn`: print the full agent guide + tool catalog
• `list`: apps, windows, screens, menubar, permissions
• `permissions`: check Screen Recording/Accessibility status
• `run`: execute `.peekaboo.json` scripts
• `sleep`: pause execution for a duration
• `tools`: list available tools with filtering/display options

Interaction

• `click`: target by ID/query/coords with smart waits
• `drag`: drag & drop across elements/coords/Dock
• `hotkey`: modifier combos like `cmd,shift,t`
• `move`: cursor positioning with optional smoothing
• `paste`: set clipboard -> paste -> restore
• `press`: special-key sequences with repeats
• `scroll`: directional scrolling (targeted + smooth)
• `swipe`: gesture-style drags between targets
• `type`: text + control keys (`--clear`, delays)

System

• `app`: launch/quit/relaunch/hide/unhide/switch/list apps
• `clipboard`: read/write clipboard (text/images/files)
• `dialog`: click/input/file/dismiss/list system dialogs
• `dock`: launch/right-click/hide/show/list Dock items
• `menu`: click/list application menus + menu extras
• `menubar`: list/click status bar items
• `open`: enhanced `open` with app targeting + JSON payloads
• `space`: list/switch/move-window (Spaces)
• `visualizer`: exercise Peekaboo visual feedback animations
• `window`: 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 from `see`; 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.
• Use `peekaboo see --annotate` to identify targets before clicking.