Skip to content

docs: route Peekaboo automation through app host #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
steipete merged 1 commit into from
Jul 1, 2026
Merged

docs: route Peekaboo automation through app host #22

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions skills/peekaboo/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,14 @@ Use for macOS screen capture, UI inspection, and GUI automation.
- Else use `peekaboo`.
- Check first: `~/bin/peekaboo --version || peekaboo --version`.

## Mac app host

- Launch `Peekaboo.app` before live capture/automation; the CLI does not auto-launch it.
- The app owns TCC grants and serves `~/Library/Application Support/Peekaboo/bridge.sock`.
- Installed app: `open -a Peekaboo`. Repo build: build the `Apps/Mac/Peekaboo.xcodeproj` `Peekaboo` scheme, then open the resulting `Peekaboo.app`.
- `peekaboo daemon start` is not an app launch; the daemon has separate permissions and `daemon.sock`.
- Verify `peekaboo bridge status --verbose --json --bridge-socket "$HOME/Library/Application Support/Peekaboo/bridge.sock"` selects `hostKind: gui`.

## Safety

- Check permissions before capture/automation: `peekaboo permissions status --json`.
Expand All @@ -29,6 +37,8 @@ Use for macOS screen capture, UI inspection, and GUI automation.
PB="${PEEKABOO_BIN:-$HOME/bin/peekaboo}"
[ -x "$PB" ] || PB="$(command -v peekaboo)"

open -a Peekaboo
"$PB" bridge status --verbose --json --bridge-socket "$HOME/Library/Application Support/Peekaboo/bridge.sock"

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Pin the GUI socket for follow-up live commands

In environments where a healthy reusable daemon already exists, this verifies bridge.sock once but does not make the later image/see/click/type commands use that GUI host. The Peekaboo Bridge docs say default automation commands use the daemon first and only --bridge-socket or PEEKABOO_BRIDGE_SOCKET overrides host discovery, so a Mac whose TCC grants are on Peekaboo.app but not the daemon can still fail after following this block; export PEEKABOO_BRIDGE_SOCKET or pass the socket on the live commands.

Useful? React with 👍 / 👎.

"$PB" permissions status --json
"$PB" list screens --json
"$PB" list apps --json
Expand All @@ -44,11 +54,12 @@ PB="${PEEKABOO_BIN:-$HOME/bin/peekaboo}"
## 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.
2. For live UI work, launch `Peekaboo.app`; verify the GUI bridge and its permissions.
3. Run `permissions status --json`; if missing TCC, report exact missing grant.
4. For screenshots, use `image`; include `--path`, `--json`, and usually `--no-remote` only when deliberately testing caller-local TCC.

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Remove --no-remote from the default screenshot path

This newly narrows --no-remote to caller-local TCC tests, but the Common Commands screenshot example above still includes --no-remote, so agents copying the default capture command will bypass the launched app/Bridge path. Peekaboo's Bridge docs state that --no-remote forces local execution, which means normal screenshots will still lose the app-held TCC grants this change is trying to use; please remove it from the default example or label that example as local-TCC-only.

Useful? React with 👍 / 👎.

5. For element targeting, run `see --json --annotate`, then click by element id/snapshot.
6. For long-running/change-aware screen capture, use `capture live`; for video frame sampling, use `capture video`.
7. Use `tools --json` for command/tool discovery and `learn` when the full agent guide is useful.
8. Verify output files with `sips -g pixelWidth -g pixelHeight <path>` or view the image.

Docs: `~/Projects/Peekaboo/docs/commands/`.