repositories
loading repo index
repositories
loading repo index
repository
loading code, commits, and activity
public Clawd ADK gateway launch mirror
stars
latest
clone command
git clone gitlawb://did:key:z6Mkq5mY...iFZ5/my-project-publ...git clone gitlawb://did:key:z6Mkq5mY.../my-project-publ...2fa351d6docs: add automaton and perps launch sources16d ago| #1 | --- |
| #2 | name: peekaboo |
| #3 | description: Capture and automate macOS UI with the Peekaboo CLI. |
| #4 | homepage: https://peekaboo.boo |
| #5 | metadata: {"clawdbot":{"emoji":"👀","os":["darwin"],"requires":{"bins":["peekaboo"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/peekaboo","bins":["peekaboo"],"label":"Install Peekaboo (brew)"}]}} |
| #6 | --- |
| #7 | |
| #8 | # Peekaboo |
| #9 | |
| #10 | Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI |
| #11 | elements, drive input, and manage apps/windows/menus. Commands share a snapshot |
| #12 | cache and support `--json`/`-j` for scripting. Run `peekaboo` or |
| #13 | `peekaboo <cmd> --help` for flags; `peekaboo --version` prints build metadata. |
| #14 | Tip: run via `polter peekaboo` to ensure fresh builds. |
| #15 | |
| #16 | ## Features (all CLI capabilities, excluding agent/MCP) |
| #17 | |
| #18 | Core |
| #19 | - `bridge`: inspect Peekaboo Bridge host connectivity |
| #20 | - `capture`: live capture or video ingest + frame extraction |
| #21 | - `clean`: prune snapshot cache and temp files |
| #22 | - `config`: init/show/edit/validate, providers, models, credentials |
| #23 | - `image`: capture screenshots (screen/window/menu bar regions) |
| #24 | - `learn`: print the full agent guide + tool catalog |
| #25 | - `list`: apps, windows, screens, menubar, permissions |
| #26 | - `permissions`: check Screen Recording/Accessibility status |
| #27 | - `run`: execute `.peekaboo.json` scripts |
| #28 | - `sleep`: pause execution for a duration |
| #29 | - `tools`: list available tools with filtering/display options |
| #30 | |
| #31 | Interaction |
| #32 | - `click`: target by ID/query/coords with smart waits |
| #33 | - `drag`: drag & drop across elements/coords/Dock |
| #34 | - `hotkey`: modifier combos like `cmd,shift,t` |
| #35 | - `move`: cursor positioning with optional smoothing |
| #36 | - `paste`: set clipboard -> paste -> restore |
| #37 | - `press`: special-key sequences with repeats |
| #38 | - `scroll`: directional scrolling (targeted + smooth) |
| #39 | - `swipe`: gesture-style drags between targets |
| #40 | - `type`: text + control keys (`--clear`, delays) |
| #41 | |
| #42 | System |
| #43 | - `app`: launch/quit/relaunch/hide/unhide/switch/list apps |
| #44 | - `clipboard`: read/write clipboard (text/images/files) |
| #45 | - `dialog`: click/input/file/dismiss/list system dialogs |
| #46 | - `dock`: launch/right-click/hide/show/list Dock items |
| #47 | - `menu`: click/list application menus + menu extras |
| #48 | - `menubar`: list/click status bar items |
| #49 | - `open`: enhanced `open` with app targeting + JSON payloads |
| #50 | - `space`: list/switch/move-window (Spaces) |
| #51 | - `visualizer`: exercise Peekaboo visual feedback animations |
| #52 | - `window`: close/minimize/maximize/move/resize/focus/list |
| #53 | |
| #54 | Vision |
| #55 | - `see`: annotated UI maps, snapshot IDs, optional analysis |
| #56 | |
| #57 | Global runtime flags |
| #58 | - `--json`/`-j`, `--verbose`/`-v`, `--log-level <level>` |
| #59 | - `--no-remote`, `--bridge-socket <path>` |
| #60 | |
| #61 | ## Quickstart (happy path) |
| #62 | ```bash |
| #63 | peekaboo permissions |
| #64 | peekaboo list apps --json |
| #65 | peekaboo see --annotate --path /tmp/peekaboo-see.png |
| #66 | peekaboo click --on B1 |
| #67 | peekaboo type "Hello" --return |
| #68 | ``` |
| #69 | |
| #70 | ## Common targeting parameters (most interaction commands) |
| #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 | - Output: `--path`, `--format png|jpg`, `--retina` |
| #79 | - Targeting: `--mode screen|window|frontmost`, `--screen-index`, |
| #80 | `--window-title`, `--window-id` |
| #81 | - Analysis: `--analyze "prompt"`, `--annotate` |
| #82 | - Capture engine: `--capture-engine auto|classic|cg|modern|sckit` |
| #83 | |
| #84 | ## Common motion/typing parameters |
| #85 | - Timing: `--duration` (drag/swipe), `--steps`, `--delay` (type/scroll/press) |
| #86 | - Human-ish movement: `--profile human|linear`, `--wpm` (typing) |
| #87 | - Scroll: `--direction up|down|left|right`, `--amount <ticks>`, `--smooth` |
| #88 | |
| #89 | ## Examples |
| #90 | ### See -> click -> type (most reliable flow) |
| #91 | ```bash |
| #92 | peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png |
| #93 | peekaboo click --on B3 --app Safari |
| #94 | peekaboo type "user@example.com" --app Safari |
| #95 | peekaboo press tab --count 1 --app Safari |
| #96 | peekaboo type "supersecret" --app Safari --return |
| #97 | ``` |
| #98 | |
| #99 | ### Target by window id |
| #100 | ```bash |
| #101 | peekaboo list windows --app "Visual Studio Code" --json |
| #102 | peekaboo click --window-id 12345 --coords 120,160 |
| #103 | peekaboo type "Hello from Peekaboo" --window-id 12345 |
| #104 | ``` |
| #105 | |
| #106 | ### Capture screenshots + analyze |
| #107 | ```bash |
| #108 | peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png |
| #109 | peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs" |
| #110 | peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard" |
| #111 | ``` |
| #112 | |
| #113 | ### Live capture (motion-aware) |
| #114 | ```bash |
| #115 | peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \ |
| #116 | --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture |
| #117 | ``` |
| #118 | |
| #119 | ### App + window management |
| #120 | ```bash |
| #121 | peekaboo app launch "Safari" --open https://example.com |
| #122 | peekaboo window focus --app Safari --window-title "Example" |
| #123 | peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800 |
| #124 | peekaboo app quit --app Safari |
| #125 | ``` |
| #126 | |
| #127 | ### Menus, menubar, dock |
| #128 | ```bash |
| #129 | peekaboo menu click --app Safari --item "New Window" |
| #130 | peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts" |
| #131 | peekaboo menu click-extra --title "WiFi" |
| #132 | peekaboo dock launch Safari |
| #133 | peekaboo menubar list --json |
| #134 | ``` |
| #135 | |
| #136 | ### Mouse + gesture input |
| #137 | ```bash |
| #138 | peekaboo move 500,300 --smooth |
| #139 | peekaboo drag --from B1 --to T2 |
| #140 | peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800 |
| #141 | peekaboo scroll --direction down --amount 6 --smooth |
| #142 | ``` |
| #143 | |
| #144 | ### Keyboard input |
| #145 | ```bash |
| #146 | peekaboo hotkey --keys "cmd,shift,t" |
| #147 | peekaboo press escape |
| #148 | peekaboo type "Line 1\nLine 2" --delay 10 |
| #149 | ``` |
| #150 | |
| #151 | Notes |
| #152 | - Requires Screen Recording + Accessibility permissions. |
| #153 | - Use `peekaboo see --annotate` to identify targets before clicking. |
| #154 |