peekaboo
starsforks
How to install peekaboo?
safeai-lab-x/clawkeeper/peekaboo
$npx -y skills add SafeAI-Lab-X/ClawKeeper --skill peekabooCapture and automate macOS UI with the Peekaboo CLI.
SKILL.md
| 1 | # Peekaboo |
| 2 | |
| 3 | Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI |
| 4 | elements, drive input, and manage apps/windows/menus. Commands share a snapshot |
| 5 | cache and support `--json`/`-j` for scripting. Run `peekaboo` or |
| 6 | `peekaboo <cmd> --help` for flags; `peekaboo --version` prints build metadata. |
| 7 | Tip: run via `polter peekaboo` to ensure fresh builds. |
| 8 | |
| 9 | ## Features (all CLI capabilities, excluding agent/MCP) |
| 10 | |
| 11 | Core |
| 12 | |
| 13 | - `bridge`: inspect Peekaboo Bridge host connectivity |
| 14 | - `capture`: live capture or video ingest + frame extraction |
| 15 | - `clean`: prune snapshot cache and temp files |
| 16 | - `config`: init/show/edit/validate, providers, models, credentials |
| 17 | - `image`: capture screenshots (screen/window/menu bar regions) |
| 18 | - `learn`: print the full agent guide + tool catalog |
| 19 | - `list`: apps, windows, screens, menubar, permissions |
| 20 | - `permissions`: check Screen Recording/Accessibility status |
| 21 | - `run`: execute `.peekaboo.json` scripts |
| 22 | - `sleep`: pause execution for a duration |
| 23 | - `tools`: list available tools with filtering/display options |
| 24 | |
| 25 | Interaction |
| 26 | |
| 27 | - `click`: target by ID/query/coords with smart waits |
| 28 | - `drag`: drag & drop across elements/coords/Dock |
| 29 | - `hotkey`: modifier combos like `cmd,shift,t` |
| 30 | - `move`: cursor positioning with optional smoothing |
| 31 | - `paste`: set clipboard -> paste -> restore |
| 32 | - `press`: special-key sequences with repeats |
| 33 | - `scroll`: directional scrolling (targeted + smooth) |
| 34 | - `swipe`: gesture-style drags between targets |
| 35 | - `type`: text + control keys (`--clear`, delays) |
| 36 | |
| 37 | System |
| 38 | |
| 39 | - `app`: launch/quit/relaunch/hide/unhide/switch/list apps |
| 40 | - `clipboard`: read/write clipboard (text/images/files) |
| 41 | - `dialog`: click/input/file/dismiss/list system dialogs |
| 42 | - `dock`: launch/right-click/hide/show/list Dock items |
| 43 | - `menu`: click/list application menus + menu extras |
| 44 | - `menubar`: list/click status bar items |
| 45 | - `open`: enhanced `open` with app targeting + JSON payloads |
| 46 | - `space`: list/switch/move-window (Spaces) |
| 47 | - `visualizer`: exercise Peekaboo visual feedback animations |
| 48 | - `window`: close/minimize/maximize/move/resize/focus/list |
| 49 | |
| 50 | Vision |
| 51 | |
| 52 | - `see`: annotated UI maps, snapshot IDs, optional analysis |
| 53 | |
| 54 | Global runtime flags |
| 55 | |
| 56 | - `--json`/`-j`, `--verbose`/`-v`, `--log-level <level>` |
| 57 | - `--no-remote`, `--bridge-socket <path>` |
| 58 | |
| 59 | ## Quickstart (happy path) |
| 60 | |
| 61 | ```bash |
| 62 | peekaboo permissions |
| 63 | peekaboo list apps --json |
| 64 | peekaboo see --annotate --path /tmp/peekaboo-see.png |
| 65 | peekaboo click --on B1 |
| 66 | peekaboo type "Hello" --return |
| 67 | ``` |
| 68 | |
| 69 | ## Common targeting parameters (most interaction commands) |
| 70 | |
| 71 | - App/window: `--app`, `--pid`, `--window-title`, `--window-id`, `--window-index` |
| 72 | - Snapshot targeting: `--snapshot` (ID from `see`; defaults to latest) |
| 73 | - Element/coords: `--on`/`--id` (element ID), `--coords x,y` |
| 74 | - Focus control: `--no-auto-focus`, `--space-switch`, `--bring-to-current-space`, |
| 75 | `--focus-timeout-seconds`, `--focus-retry-count` |
| 76 | |
| 77 | ## Common capture parameters |
| 78 | |
| 79 | - Output: `--path`, `--format png|jpg`, `--retina` |
| 80 | - Targeting: `--mode screen|window|frontmost`, `--screen-index`, |
| 81 | `--window-title`, `--window-id` |
| 82 | - Analysis: `--analyze "prompt"`, `--annotate` |
| 83 | - Capture engine: `--capture-engine auto|classic|cg|modern|sckit` |
| 84 | |
| 85 | ## Common motion/typing parameters |
| 86 | |
| 87 | - Timing: `--duration` (drag/swipe), `--steps`, `--delay` (type/scroll/press) |
| 88 | - Human-ish movement: `--profile human|linear`, `--wpm` (typing) |
| 89 | - Scroll: `--direction up|down|left|right`, `--amount <ticks>`, `--smooth` |
| 90 | |
| 91 | ## Examples |
| 92 | |
| 93 | ### See -> click -> type (most reliable flow) |
| 94 | |
| 95 | ```bash |
| 96 | peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png |
| 97 | peekaboo click --on B3 --app Safari |
| 98 | peekaboo type "user@example.com" --app Safari |
| 99 | peekaboo press tab --count 1 --app Safari |
| 100 | peekaboo type "supersecret" --app Safari --return |
| 101 | ``` |
| 102 | |
| 103 | ### Target by window id |
| 104 | |
| 105 | ```bash |
| 106 | peekaboo list windows --app "Visual Studio Code" --json |
| 107 | peekaboo click --window-id 12345 --coords 120,160 |
| 108 | peekaboo type "Hello from Peekaboo" --window-id 12345 |
| 109 | ``` |
| 110 | |
| 111 | ### Capture screenshots + analyze |
| 112 | |
| 113 | ```bash |
| 114 | peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png |
| 115 | peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs" |
| 116 | peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard" |
| 117 | ``` |
| 118 | |
| 119 | ### Live capture (motion-aware) |
| 120 | |
| 121 | ```bash |
| 122 | peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \ |
| 123 | --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture |
| 124 | ``` |
| 125 | |
| 126 | ### App + window management |
| 127 | |
| 128 | ```bash |
| 129 | peekaboo app launch |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
