peekaboo

---
name: peekaboo
description: Use when working with macOS screenshots, UI inspect, clicks, typing, app/window automation from steipete/agent-scripts.
source: https://github.com/steipete/agent-scripts/tree/main/skills/peekaboo
generated: 2026-05-27T20:56:18.542Z
category: tool
audience: engineers
---

## When to use

- MacOS screen capture, UI inspection, and GUI automation.
- Using the peekaboo skill's upstream workflow, guardrails, and local-tool assumptions.
- Auditing commands or operational steps before changing peekaboo behavior.
- Needing a compact agent reference for macOS screenshots, UI inspect, clicks, typing, app/window automation.

## Key concepts

### Binary

Prefer ~/bin/peekaboo when present; it is Peter's local release copy. Else use peekaboo. Check first: ~/bin/peekaboo --version || peekaboo --version.

### Safety

Check permissions before capture/automation: peekaboo permissions status --json. Screenshot needs Screen Recording; clicks/typing/window control need Accessibility. On remote Macs, Screenshot may be blocked by missing Screen Recording while clicks/typing still work through Accessibility; continue with clicks or DOM automation when the target is otherwise knowable. Prefer --json for machine parsing and --no-remote when testing local TCC. Do not click/type/destructively automate unless user...

### Common Commands

Common Commands guidance for the peekaboo skill.

### Workflow

1. Resolve PB as above and confirm version when install state matters. 2. Run permissions status --json; if missing TCC, report exact missing grant. 3. For screenshots, use image; include --path, --json, and usually --no-remote. 4. For element targeting, run see --json --annotate, then click by element id/snapshot. 5. For long-running/change-aware screen capture, use capture live; for video frame sampling, use capture video. 6. Use tools --json for command/tool discovery and learn when the...

## API reference

```
npx skills add steipete/agent-scripts --skill peekaboo
```

Install the peekaboo skill from steipete/agent-scripts.

```
npx skills add steipete/agent-scripts --skill peekaboo
```

```
PB="${PEEKABOOBIN:-$HOME/bin/peekaboo}".
```

Command or snippet documented by the upstream peekaboo skill.

```
PB="${PEEKABOO_BIN:-$HOME/bin/peekaboo}"
[ -x "$PB" ] || PB="$(command -v peekaboo)"

"$PB" permissions status --json
"$PB" list screens --json
"$PB" list apps --json
"$PB" list windows --app Safari --json
"$PB" image --mode screen --screen-index 0 --path /tmp/screen.png --json --no-remote
"$PB" see --app frontmost --path /tmp/frontmost.png --json --annotate
"$PB" tools --json
"$PB" learn
"$PB" click --coords 100,100 --json
"$PB" type "text" --json
```

## Gotchas

- Prefer ~/bin/peekaboo when present; it is Peter's local release copy.
- Prefer --json for machine parsing and --no-remote when testing local TCC.
- Do not click/type/destructively automate unless user asked or target is a controlled test.

---
Generated by SkillMake from https://github.com/steipete/agent-scripts/tree/main/skills/peekaboo on 2026-05-27T20:56:18.542Z.
Verify against source before relying on details.

File: ~/.claude/skills/peekaboo/SKILL.md