Start

Quickstart

Home GitHub Edit page

Quickstart

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

grant opens System Settings to the right pane. You need Screen Recording (required) and Accessibility (recommended). Re-run permissions status until both are green. Background hotkeys also need Event Synthesizing — see permissions.md.

#2. Take a screenshot

# whole screen → ./screen.png
peekaboo capture --output screen.png

# only the focused window
peekaboo capture --window-focused --output focused.png

# a specific app's frontmost window
peekaboo capture --app Safari --output safari.png

The output is a regular PNG. Add --format jpeg --quality 85 for smaller files. See commands/capture.md for every flag.

#3. Inspect the UI

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

peekaboo see --app Safari --json | jq '.elements[0:3]'

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

peekaboo see --app Safari --annotate --output 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 --label "Address and search bar" --app Safari
peekaboo type "github.com/steipete/Peekaboo" --press-return

Coordinates also work: peekaboo click --at 480,120. See automation.md for the full input vocabulary.

#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"

Watch the visualizer overlay as it works. Pause/resume 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?