Peekaboo
Drive macOS UI automation from your coding agent—screenshots, window/app control, menus, and scripted `.peekaboo.json` runs via the Peekaboo CLI.
Overview
Peekaboo is an agent skill for the Build phase that captures and automates macOS UI through the Peekaboo CLI (screens, elements, input, apps, and scripted runs).
Install
npx skills add https://github.com/steipete/clawdis --skill peekabooWhat is this skill?
- Full macOS UI automation CLI: capture, inspect, click, type, scroll, and run snapshot-backed scripts
- Core commands include `image`, `list`, `run`, `capture`, `config`, `permissions`, and `bridge` with shared snapshot cach
- JSON output via `--json`/`-j` for agent scripting and programmatic parsing
- Documents Screen Recording and Accessibility permission checks via `permissions` and `list`
- Homebrew install path (`steipete/tap/peekaboo`) with OpenClaw metadata requiring the `peekaboo` binary on darwin
Adoption & trust: 2.6k installs on skills.sh; 378k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want your agent to operate real macOS UI—not only read files—but you lack a documented, scriptable command map and install path.
Who is it for?
Solo builders on macOS who automate desktop QA, capture marketing screenshots, or script window/app workflows from an OpenClaw- or Claude-style agent.
Skip if: Linux or Windows hosts, headless-only servers with no GUI, or teams that only need in-browser automation without native macOS UI access.
When should I use this skill?
You need macOS UI capture, inspection, or scripted automation via the installed `peekaboo` binary on darwin.
What do I get? / Deliverables
Your agent runs documented Peekaboo commands with JSON-friendly flags, respects permissions checks, and can chain repeatable UI automation instead of fragile ad-hoc AppleScript.
- CLI-driven screenshots and UI snapshots
- Enumerated apps/windows/screens output
- Executed `.peekaboo.json` automation scripts
Recommended Skills
Journey fit
Peekaboo is installed as agent capability wiring: it extends what Claude/OpenClaw can do on a Mac during product build and local tooling work. agent-tooling is the canonical shelf for skills that require a host binary and expose CLI workflows to the agent, not app feature code inside your repo.
How it compares
Use as a documented macOS UI CLI integration—not as a cross-platform Playwright substitute or a generic screenshot shell alias.
Common Questions / FAQ
Who is peekaboo for?
Indie and solo developers on macOS who want their coding agent to capture UI, inspect windows/apps, and run Peekaboo automation scripts with brew-installed tooling.
When should I use peekaboo?
During Build agent-tooling work when you need live screen capture, element-targeted input, permission diagnostics, or `.peekaboo.json` runs on a Mac dev machine.
Is peekaboo safe to install?
It requires a third-party CLI and macOS accessibility/screen-recording permissions; review the Security Audits panel on this page and limit agent shell access to trusted repos.
SKILL.md
READMESKILL.md - Peekaboo
# 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) ```bash 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) `