From 6cdfd143b0bebf35be8c45be7579356052be3faf Mon Sep 17 00:00:00 2001 From: Petter Blomberg Date: Thu, 1 Jan 2026 15:38:27 +0100 Subject: [PATCH] docs: add macOS developer setup and troubleshooting guides --- docs/mac/dev-setup.md | 81 +++++++++++++++++++++++++++++++++++++++++ docs/mac/signing.md | 17 ++------- docs/troubleshooting.md | 29 +++++++++++++++ 3 files changed, 114 insertions(+), 13 deletions(-) create mode 100644 docs/mac/dev-setup.md diff --git a/docs/mac/dev-setup.md b/docs/mac/dev-setup.md new file mode 100644 index 000000000..1cd80fc12 --- /dev/null +++ b/docs/mac/dev-setup.md @@ -0,0 +1,81 @@ +--- +summary: "Setup guide for developers working on the Clawdis macOS app" +read_when: + - Setting up the macOS development environment +--- +# macOS Developer Setup + +This guide covers the necessary steps to build and run the Clawdis macOS application from source. + +## Prerequisites + +Before building the app, ensure you have the following installed: + +1. **Xcode**: Required for Swift development. +2. **Node.js & pnpm**: Required for the gateway and CLI components. +3. **Bun**: Required to package the embedded gateway relay. + ```bash + curl -fsSL https://bun.sh/install | bash + ``` + +## 1. Initialize Submodules + +Clawdis 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/Clawdis.app`, run: + +```bash +./scripts/package-mac-app.sh +``` + +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 `clawdis` in `/usr/local/bin` or `/opt/homebrew/bin` to manage background tasks. + +**To install it:** +1. Open the Clawdis 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)/clawdis/dist/Clawdis.app/Contents/Resources/Relay/clawdis" /usr/local/bin/clawdis +``` + +## Troubleshooting + +### 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.steipete.clawdis.debug + ``` +2. If that fails, change the `BUNDLE_ID` temporarily in `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 +lsof -nP -i :18789 +``` +Kill any existing `node` or `clawdis` processes listening on that port and restart the app. diff --git a/docs/mac/signing.md b/docs/mac/signing.md index 05c1b4bb5..2740eb46c 100644 --- a/docs/mac/signing.md +++ b/docs/mac/signing.md @@ -11,7 +11,8 @@ This app is usually built from `scripts/package-mac-app.sh`, which now: - writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`) - calls `scripts/codesign-mac-app.sh` to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). Requires a valid signing identity. - uses `CODESIGN_TIMESTAMP=auto` by default; it enables trusted timestamps for Developer ID signatures. Set `CODESIGN_TIMESTAMP=off` to skip timestamping (offline debug builds). -- injects build metadata into Info.plist: `ClawdisBuildTimestamp` (UTC) and `ClawdisGitCommit` (short hash) so the About pane can show build, git, and debug/release channel. +- inject build metadata into Info.plist: `ClawdisBuildTimestamp` (UTC) and `ClawdisGitCommit` (short hash) so the About pane can show build, git, and debug/release channel. +- **Packaging requires Bun**: The embedded gateway relay is compiled using `bun`. Ensure it is installed (`curl -fsSL https://bun.sh/install | bash`). - reads `SIGN_IDENTITY` from the environment. Add `export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"` (or your Developer ID Application cert) to your shell rc to always sign with your cert; otherwise signing falls back to ad‑hoc. ## Usage @@ -20,20 +21,10 @@ This app is usually built from `scripts/package-mac-app.sh`, which now: # from repo root scripts/package-mac-app.sh # ad-hoc signing SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh # real cert - -# set it once in your shell profile for convenience -echo 'export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"' >> ~/.zshrc ``` -If you need a different bundle id (e.g. release build): - -```bash -BUNDLE_ID=com.steipete.clawdis scripts/package-mac-app.sh -``` - -Signing identity selection: -- If `SIGN_IDENTITY` is unset, the script auto-picks a valid identity (Developer ID → Apple Distribution → Apple Development). -- If no identities exist, the script fails with an error (no ad‑hoc fallback). +### Ad-hoc Signing Note +When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. ## Build metadata for About diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index cc8c01dfa..058d6e726 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -134,6 +134,35 @@ CLAWDIS keeps conversation history in memory. } ``` +## macOS Specific Issues + +### App Crashes when Granting Permissions (Speech/Mic) + +If the app disappears or shows "Abort trap 6" when you click "Allow" on a privacy prompt: + +**Fix 1: Reset TCC Cache** +```bash +tccutil reset All com.steipete.clawdis.debug +``` + +**Fix 2: Force New Bundle ID** +If resetting doesn't work, change the `BUNDLE_ID` in `scripts/package-mac-app.sh` (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app. + +### Gateway stuck on "Starting..." + +The app connects to a local gateway on port `18789`. If it stays stuck: + +**Fix 1: Kill Zombie Processes** +Another process might be holding the port. +```bash +lsof -nP -i :18789 +# Kill any matching PIDs +kill -9 +``` + +**Fix 2: Check embedded gateway** +Ensure the gateway relay was properly bundled. Run `./scripts/package-mac-app.sh` and ensure `bun` is installed. + ## Debug Mode Get verbose logging: