---
summary: "Setup guide for developers working on the Clawdbot macOS app"
read_when:
  - Setting up the macOS development environment
---
# macOS Developer Setup

This guide covers the necessary steps to build and run the Clawdbot macOS application from source.

## Prerequisites

Before building the app, ensure you have the following installed:

1.  **Xcode 26.2+**: Required for Swift development.
2.  **Node.js & pnpm**: Required for the gateway and CLI components.
3.  **Node**: Required to package the embedded gateway relay (the script can download a bundled runtime).

## 1. Initialize Submodules

Clawdbot depends on several submodules (like `Peekaboo`). You must initialize these recursively:

```bash
git submodule update --init --recursive
```

## 2. Install Dependencies

Install the project-wide dependencies:

```bash
pnpm install
```

## 3. Build and Package the App

To build the macOS app and package it into `dist/Clawdbot.app`, run:

```bash
./scripts/package-mac-app.sh
```

Use `BUNDLED_RUNTIME=node|bun` to switch the embedded gateway runtime (default: node).

If you don't have an Apple Developer ID certificate, the script will automatically use **ad-hoc signing** (`-`). 

> **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.

## 4. Install the CLI Helper

The macOS app requires a symlink named `clawdbot` in `/usr/local/bin` or `/opt/homebrew/bin` to manage background tasks.

**To install it:**
1.  Open the Clawdbot app.
2.  Go to the **General** settings tab.
3.  Click **"Install CLI helper"** (requires administrator privileges).

Alternatively, you can manually link it from your Admin account:
```bash
sudo ln -sf "/Users/$(whoami)/Projects/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot
```

## Troubleshooting

### Build Fails: Toolchain or SDK Mismatch
The macOS app build expects the latest macOS SDK and Swift 6.2 toolchain.

**System dependencies (required):**
- **Latest macOS version available in Software Update** (required by Xcode 26.2 SDKs)
- **Xcode 26.2** (Swift 6.2 toolchain)

**Checks:**
```bash
xcodebuild -version
xcrun swift --version
```

If versions don’t match, update macOS/Xcode and re-run the build.

### App Crashes on Permission Grant
If the app crashes when you try to allow **Speech Recognition** or **Microphone** access, it may be due to a corrupted TCC cache or signature mismatch.

**Fix:**
1. Reset the TCC permissions:
   ```bash
   tccutil reset All com.clawdbot.mac.debug
   ```
2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) to force a "clean slate" from macOS.

### Gateway "Starting..." indefinitely
If the gateway status stays on "Starting...", check if a zombie process is holding the port:

```bash
clawdbot daemon status
clawdbot daemon stop

# If you’re not using a LaunchAgent (dev mode / manual runs), find the listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN
```
If a manual run is holding the port, stop that process (Ctrl+C). As a last resort, kill the PID you found above.