Skip to main content

​
Clawdbot macOS Companion (menu bar + gateway broker)

The macOS app is the menu‑bar companion for Clawdbot. It owns permissions, manages the Gateway locally, and exposes macOS capabilities to the agent as a node.

​
What it does

  • Shows native notifications and status in the menu bar.
  • Owns TCC prompts (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Automation/AppleScript).
  • Runs or connects to the Gateway (local or remote).
  • Exposes macOS‑only tools (Canvas, Camera, Screen Recording, system.run).
  • Optionally hosts PeekabooBridge for UI automation.
  • Installs a helper CLI (clawdbot) into /usr/local/bin and /opt/homebrew/bin on request.

​
Local vs remote mode

  • Local (default): the app ensures a local Gateway is running via launchd.
  • Remote: the app connects to a Gateway over SSH/Tailscale and never starts a local process.
  • Attach‑only (debug): the app connects to an already‑running local Gateway and never spawns its own.

​
Launchd control

The app manages a per‑user LaunchAgent labeled com.clawdbot.gateway. 
launchctl kickstart -k gui/$UID/com.clawdbot.gateway
launchctl bootout gui/$UID/com.clawdbot.gateway
If the LaunchAgent isn’t installed, enable it from the app or run clawdbot daemon install.

​
Node capabilities (mac)

The macOS app presents itself as a node. Common commands:
  • Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
  • Camera: camera.snap, camera.clip
  • Screen: screen.record
  • System: system.run, system.notify
The node reports a permissions map so agents can decide what’s allowed. The app registers the clawdbot:// URL scheme for local actions.

​
clawdbot://agent

Triggers a Gateway agent request. 
open 'clawdbot://agent?message=Hello%20from%20deep%20link'
Query parameters:
  • message (required)
  • sessionKey (optional)
  • thinking (optional)
  • deliver / to / provider (optional)
  • timeoutSeconds (optional)
  • key (optional unattended mode key)
Safety:
  • Without key, the app prompts for confirmation.
  • With a valid key, the run is unattended (intended for personal automations).

​
Onboarding flow (typical)

  1. Install and launch Clawdbot.app.
  2. Complete the permissions checklist (TCC prompts).
  3. Ensure Local mode is active and the Gateway is running.
  4. Install the CLI helper if you want terminal access.

​
Build & dev workflow (native)

  • cd apps/macos && swift build
  • swift run Clawdbot (or Xcode)
  • Package app + CLI: scripts/package-mac-app.sh