Quickstart

August 16, 2026 · View on GitHub

This page assumes you've already followed install.md. If peekaboo --version prints a version, you're ready.

1. Grant permissions

peekaboo permissions status
peekaboo permissions grant
peekaboo permissions request screen-recording

grant opens System Settings to the right pane. You need Screen Recording and Accessibility; both are required. Re-run permissions status until both are green. Background keyboard input and foreground synthetic pointer tools need Event Synthesizing; it is an action-specific grant rather than a global requirement. Background element/query/coordinate clicks use Accessibility. See permissions.md.

2. Take a screenshot

# whole screen -> ./screen.png
peekaboo see --no-elements --mode screen --path screen.png

# only the focused window
peekaboo see --no-elements --mode frontmost --path focused.png

# a specific app's frontmost window
peekaboo see --no-elements --app Safari --path safari.png

The output is a regular PNG. Add --format jpg for JPEG output. See commands/see.md for every flag.

If you are running from SSH, a LaunchAgent, Codex, or another background launchd session, use a Peekaboo Bridge host with Screen Recording permission. --capture-engine keeps that selected host; caller-local overrides require --no-remote and are for debugging because they can produce wallpaper-only screenshots in background sessions.

Normal CLI automation uses a healthy reusable daemon, then a capable Peekaboo.app Bridge host, and otherwise starts the daemon on demand. peekaboo bridge status --verbose shows the selected runtime.

3. Inspect the UI

see returns a structured map of clickable elements with fresh IDs:

peekaboo see --app Safari --json --path /tmp/safari-see.png | jq '.data.ui_elements[0:3]'

Add --annotate to write a labelled PNG you can eyeball:

peekaboo see --app Safari --annotate --path /tmp/safari.png

Each element has id, role, label, frame, and actions. Pass an id to other commands to act on it.

4. Click and type

peekaboo click "Address and search bar" --app Safari
peekaboo type "github.com/openclaw/Peekaboo" --app Safari
peekaboo press Return --app Safari --foreground

Coordinate clicks need a fresh capture receipt and an exact target in the default background mode. First run peekaboo window list --app Safari --json, copy the intended window_id, and capture that exact window:

CAPTURE=$(peekaboo see --window-id "$WINDOW_ID" --no-elements --json)
SNAPSHOT_ID=$(printf '%s' "$CAPTURE" | jq -r '.data.snapshot_id')
peekaboo click --window-id "$WINDOW_ID" --snapshot "$SNAPSHOT_ID" --at 480,120

The point is relative to the captured window. Add --global for screen coordinates, or add --foreground only when the target app requires focused synthetic input. See automation.md for the full input vocabulary.

Targeted click and type use background delivery by default, so Safari can receive them without becoming frontmost. Raw press can stay background with a fresh exact-window/snapshot receipt; app/PID-only or targetless chords require explicit --foreground. Prefer semantic actions for background confirmation when one exists.

Targeted scroll --on <id> is background-safe through Accessibility or, for a fresh exact-window pixel snapshot of a visible WebKit surface, PID-routed wheel events. The latter reports an unverifiable effect and must be observed before retry. Targetless/smooth scroll, move, and drag use the shared physical cursor and require explicit --foreground.

5. Run an agent

The agent picks tools, plans, and executes — give it a goal in natural language:

peekaboo agent "Open Safari, go to github.com, and search for Peekaboo"

Default background work stays overlay-free so Peekaboo does not interrupt the foreground desktop. Run peekaboo visualizer when you explicitly want to exercise the overlay catalog. Continue a saved run with peekaboo agent resume <session-id>. See commands/agent.md for provider switching and session management.

6. (Optional) Wire up MCP

Want Codex, Claude Code, or Cursor to drive Peekaboo? Drop this into your MCP client config:

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": ["-y", "@steipete/peekaboo", "mcp"]
    }
  }
}

Full setup, including environment variables and provider keys, is in MCP.md.

What next?