Architecture

Peekaboo Bridge Host

Home GitHub Edit page

Peekaboo Bridge Host

Peekaboo Bridge is a socket-based broker for permission-bound operations (Screen Recording, Accessibility, AppleScript). It lets a CLI (or other client process) drive automation via a host app that already has the necessary TCC grants.

This replaces the previous XPC-based helper approach.

#Hosts and discovery (client preference order)

Clients try hosts in this order:

  1. Peekaboo.app (primary host)
  • Socket: ~/Library/Application Support/Peekaboo/bridge.sock
  1. Claude.app (fallback host; piggyback on Claude Desktop TCC grants)
  • Socket: ~/Library/Application Support/Claude/bridge.sock
  1. Clawdbot.app (fallback host)
  • Socket: ~/Library/Application Support/clawdbot/bridge.sock
  1. Local in-process (no host available; requires the caller process to have TCC grants)

There is no auto-launch of Peekaboo.app.

#Transport

  • UNIX-domain socket, single request per connection:
  • Client writes one JSON request, then half-closes.
  • Host replies with one JSON response and closes.
  • Payloads are Codable JSON with a small handshake for:
  • protocol version negotiation
  • capability/operation advertisement

Protocol 1.3 adds element action operations:

  • setValue for direct accessibility value mutation.
  • performAction for named accessibility action invocation.

#Security

Peekaboo BridgeHost validates callers before processing any request:

  • Reads the peer PID via getsockopt(..., LOCAL_PEERPID, ...).
  • Validates the peer’s code signature TeamID via Security.framework (SecCodeCopyGuestWithAttributes).
  • Rejects any process not signed by an allowlisted TeamID (default: Y5PE65HELJ).

Debug-only escape hatch:

  • Set PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 to allow same-UID unsigned clients (local dev only).

#Snapshot state

Bridge hosts are intended to be long-lived and keep automation state in memory:

  • Hosts typically use InMemorySnapshotManager so follow-up actions can reuse the “most recent snapshot” per app/bundle without passing IDs around.
  • Screenshot artifacts are still referenced by file path (e.g. in /tmp), and are not streamed incrementally.

#CLI behavior

  • By default, the CLI attempts to use a remote host when available.
  • Use --no-remote to force local execution.
  • Use --bridge-socket <path> or PEEKABOO_BRIDGE_SOCKET to override host discovery.
  • Use peekaboo bridge status to verify which host would be selected and why (probe results, handshake errors, etc.).

#Screen Recording troubleshooting

TCC permissions belong to the process that performs the capture. When the CLI routes through Bridge, Screen Recording must be granted to the selected host app, not just to the terminal, Node process, or editor that spawned peekaboo.

For subprocess runners such as OpenClaw, this means a capture can fail through Bridge even though the parent process is listed in System Settings. Check the selected host and permission source first:

peekaboo bridge status --verbose
peekaboo permissions status

If the parent process already has Screen Recording but the selected Bridge host does not, force local capture and the CoreGraphics engine:

peekaboo see --mode screen --screen-index 0 --no-remote --capture-engine cg --json