​

Clawdbot macOS IPC architecture

​

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 PeekabooBridge usage.

​

Mach/XPC

• Not required for automation; node.invoke + PeekabooBridge cover current needs.

​

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; keep the signed bundle ID stable across rebuilds.