From 23e9df68c9f7e562a091a45bdc6e9415fd19b6f6 Mon Sep 17 00:00:00 2001
From: Hutson <hutson@htsn.io>
Date: Sun, 21 Dec 2025 13:28:30 -0500
Subject: [PATCH] Update Happy Coder docs with complete setup flow and
 troubleshooting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Expand Mobile Access Setup with full authentication steps
  (HAPPY_SERVER_URL, happy auth login, happy connect claude, local claude login)
- Fix launchd path: ~/Library/LaunchAgents/ not /Library/LaunchDaemons/
- Add Common Issues troubleshooting table with fixes for:
  - Invalid API key (Claude not logged in locally)
  - Failed to start daemon (stale lock files)
  - Sessions not showing (missing HAPPY_SERVER_URL)
  - Slow responses (Cloudflare proxy enabled)
- Update DNS note: Cloudflare proxy disabled for WebSocket performance
- Add .zshrc to Files & Configuration table

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 45 ++++++++++++++++++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 9 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2cb5370..dcc8ba9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -479,8 +479,25 @@ happy daemon list
 1. Download Happy Coder app:
    - iOS: https://apps.apple.com/us/app/happy-claude-code-client/id6748571505
    - Android: https://play.google.com/store/apps/details?id=com.ex3ndr.happy
-2. On Mac Mini, run: `happy auth` and scan QR code with the app
-3. Daemon auto-starts on boot via launchd
+2. On Mac Mini, ensure self-hosted server is configured:
+   ```bash
+   echo 'export HAPPY_SERVER_URL="https://happy.htsn.io"' >> ~/.zshrc
+   source ~/.zshrc
+   ```
+3. Authenticate with the Happy server:
+   ```bash
+   happy auth login --force  # Opens browser, scan QR with app
+   ```
+4. Connect Claude API access:
+   ```bash
+   happy connect claude      # Links your Anthropic API credentials
+   ```
+5. Ensure Claude is logged in locally (critical for spawned sessions):
+   ```bash
+   claude                    # Start Claude Code
+   /login                    # Authenticate if prompted
+   ```
+6. Daemon auto-starts on login via launchd
 
 ### Daemon Management
 ```bash
@@ -506,18 +523,19 @@ cd ~/Projects/homelab && happy claude
 ### Files & Configuration
 | File | Purpose |
 |------|---------|
-| `/Library/LaunchDaemons/com.hutson.happy-daemon.plist` | System LaunchDaemon (starts at boot, KeepAlive enabled) |
-| `~/.happy/` | Happy Coder config and logs |
+| `~/Library/LaunchAgents/com.hutson.happy-daemon.plist` | User LaunchAgent (starts at login) |
+| `~/.happy/` | Happy Coder config, state, and logs |
+| `~/.zshrc` | Contains `HAPPY_SERVER_URL` export |
 
-**Server:** `https://happy.htsn.io` (self-hosted Happy server)
+**Server:** `https://happy.htsn.io` (self-hosted Happy server on docker-host)
 
 ### Troubleshooting
 ```bash
 # Check if daemon is running
-happy daemon status
+pgrep -f "happy.*daemon"
 
-# Check launchd status (system level)
-launchctl print system/com.hutson.happy-daemon | head -10
+# Check launchd status
+launchctl list | grep happy
 
 # List active sessions
 happy daemon list
@@ -529,6 +547,15 @@ happy daemon stop && happy daemon start
 /Applications/Tailscale.app/Contents/MacOS/Tailscale up
 ```
 
+**Common Issues:**
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| "Invalid API key" in spawned session | Claude not logged in locally | Run `claude` then `/login` on Mac Mini |
+| "Failed to start daemon" | Stale lock file | `rm -f ~/.happy/daemon.state.json.lock ~/.happy/daemon.state.json` |
+| Sessions not showing on phone | HAPPY_SERVER_URL not set | Add to `~/.zshrc`: `export HAPPY_SERVER_URL="https://happy.htsn.io"` |
+| Slow responses | Cloudflare proxy enabled | Disable proxy for happy.htsn.io subdomain |
+
 ## Happy Server (Self-Hosted Relay)
 
 Self-hosted Happy Coder relay server for lower latency and no external dependencies.
@@ -554,7 +581,7 @@ Phone App → https://happy.htsn.io → Traefik → docker-host:3002 → Happy S
 
 **Docker Compose**: `/opt/happy-server/docker-compose.yml`
 **Traefik Config**: `/etc/traefik/conf.d/happy.yaml` (on CT 202)
-**DNS**: happy.htsn.io → 70.237.94.174 (Cloudflare proxied)
+**DNS**: happy.htsn.io → 70.237.94.174 (Cloudflare DNS-only, NOT proxied for WebSocket performance)
 
 **Credentials**:
 - Master Secret: `3ccbfd03a028d3c278da7d2cf36d99b94cd4b1fecabc49ab006e8e89bc7707ac`