Peekabo

Overview

Use Peekaboo to see the macOS UI, capture screenshots, and drive deterministic interactions through element IDs and snapshots.

Installation

bunx @steipete/peekaboo
npx -y @steipete/peekaboo
brew install steipete/tap/peekaboo

Priority is in that order.

Workflow

1. Verify permissions.
   • Run peekaboo permissions status before any capture or interaction.
2. Identify targets.
   • Use peekaboo list or peekaboo window list --app <Name> to find apps and windows.
3. Capture a snapshot.
   • Run peekaboo see --app <Name> --json-output and keep snapshot_id.
4. Act on elements.
   • Prefer element IDs from see with click, type, scroll, drag, hotkey, press.
   • Use coordinates only when IDs are unavailable.
5. Validate.
   • Re-run see or image to confirm UI state after actions.
6. Escalate to agent when needed.
   • Use peekaboo agent "task" for multi-step natural language flows.

Quick start

peekaboo permissions status
peekaboo list
peekaboo see --app "Safari" --json-output
peekaboo click --on B12
peekaboo type "hello" --return
peekaboo image --mode screen --retina --path ~/Desktop/screen.png

Decision rules

• Use see + element IDs for reliable clicks and typing.
• Always scope actions with --app, --window-title, or --window-id when multiple windows exist.
• Use --json-output for scripting and to extract snapshot and element IDs.
• If a command fails due to focus or stale snapshots, run see again and retry with the new snapshot.

References

• Use references/peekaboo-cli.md for command summaries, flags, and examples.