clawdbot/docs/mac/xpc.md

summary, read_when

summary	read_when
macOS IPC architecture for Clawdbot app, gateway node bridge, and PeekabooBridge	Editing IPC contracts or menu bar app IPC

Clawdbot macOS IPC architecture (Dec 2025)

Current model: there is no local control socket and no clawdbot-mac CLI. All agent actions go through the Gateway WebSocket and node.invoke. UI automation still uses PeekabooBridge.

Goals

• Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).
• A small surface for automation: Gateway + node commands, plus PeekabooBridge for UI automation.
• Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick.

How it works

Gateway + node bridge (current)

• The app runs the Gateway (local mode) and connects to it as a node.
• Agent actions are performed via node.invoke (e.g. system.run, system.notify, canvas.*).

PeekabooBridge (UI automation)

• UI automation uses a separate UNIX socket named bridge.sock and the PeekabooBridge JSON protocol.
• Host preference order (client-side): Peekaboo.app → Claude.app → Clawdbot.app → local execution.
• Security: bridge hosts require TeamID Y5PE65HELJ; DEBUG-only same-UID escape hatch is guarded by PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (Peekaboo convention).
• See: docs/mac/peekaboo.md for the Clawdbot plan and naming.

Mach/XPC (future direction)

• Still optional for internal app services, but not required for automation now that node.invoke is the surface.

Operational flows

• Restart/rebuild: SIGN_IDENTITY="Apple Development: Peter Steinberger (2ZAC4GM7GD)" scripts/restart-mac.sh
  • Kills existing instances
  • Swift build + package
  • Writes/bootstraps/kickstarts the LaunchAgent
• Single instance: app exits early if another instance with the same bundle ID is running.

Hardening notes

• Prefer requiring a TeamID match for all privileged surfaces.
• PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (DEBUG-only) may allow same-UID callers for local development.
• All communication remains local-only; no network sockets are exposed.
• TCC prompts originate only from the GUI app bundle; run scripts/package-mac-app.sh so the signed bundle ID stays stable.