What does peekaboo do?
Use Peekaboo to inspect macOS UI, act on the intended target, and verify the result.
The examples below use v4 syntax. Check peekaboo --version and the installed
command's --help; for older versions, follow that version's help.
OpenClaw Bridge
The OpenClaw macOS app hosts Peekaboo Bridge when Computer Control is enabled, its provider is Peekaboo, and Peekaboo Bridge is enabled. Keep the existing OpenClaw socket selection when running through that host:
export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/OpenClaw/bridge.sock}"
peekaboo bridge status --json
Confirm that the selected host and socket are the intended ones. Preserve an
explicit PEEKABOO_BRIDGE_SOCKET or --bridge-socket selection. If the required
host is unavailable, report that outcome; do not clear the selection or switch
Computer Control providers to make a command succeed.
Permissions belong to the process or Bridge host performing the operation.
Do not pass --no-remote unless the caller has the required permissions.
Find the installed command
Use leaf help for flags and targeting requirements instead of copying a flag between commands. Use root help to discover the available commands:
peekaboo --help
peekaboo app list --help
peekaboo see --help
peekaboo press --help
peekaboo drag --help
V4 removed these old command roots:
| Old command | V4 command |
|---|---|
list apps | app list |
image | see --no-elements for pixels without element detection |
hotkey | press with chords such as cmd+shift+t |
swipe | drag --from … --to … |
For other operations, including clicking, typing, scrolling, and managing windows
or menus, use peekaboo <command> --help. Put command options after the leaf
command; --json requests structured output.
Inspect, act, verify
Start with application inventory and a fresh view of the target:
peekaboo app list --json
peekaboo see --app Safari --window-title "Example" --annotate \
--path /tmp/peekaboo-example.png --json
Read the returned elements before acting. Keep actions tied to the intended app, window, and fresh snapshot; do not reuse example element IDs. After an action, inspect the UI again and check the requested result. Refresh the observation when the window changes or a target becomes stale.
For a screenshot without element detection:
peekaboo see --mode screen --screen-index 0 --no-elements --retina \
--path /tmp/peekaboo-screen.png --json
Raw keyboard chords require explicit foreground interaction or a fresh
exact-window receipt accepted by press. Dragging always moves the shared cursor
and requires --foreground. When foreground interaction is authorized:
peekaboo press cmd+shift+t --app Safari --foreground --json
peekaboo drag --from 100,500 --to 100,200 --duration 800ms --foreground --json
Use the actual target and coordinates from the current observation. Prefer
explicit duration units such as 800ms; consult each command's help for its
options and prerequisites.
Troubleshooting
- For a removed-command error, use the replacement named by the installed CLI.
- For host or permission failures, inspect
peekaboo bridge status --jsonandpeekaboo permissions status --jsonfor the selected host. - For targeting failures, read the leaf help and obtain fresh UI state with
see. - On macOS 15+, the private window picker prompt is separate from the base Screen Recording grant and can appear even when Bridge permissions are correct.