Peekaboo

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 asked or target is a controlled test.

Common Commands

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

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 full agent guide is useful.
7. Verify output files with

   sips -g pixelWidth -g pixelHeight <path>

   or view the image.

~/Projects/Peekaboo/docs/commands/