Talk to Claude Code and Codex agents from an Apple Watch and an iPhone. Each agent is a character on the watch.
README: three watches at the top; a failed runtime switch goes back; Remote Control off in config; install and doctor fixes
Lucas Coutocd79ecbd76c0
diff --git a/README.md b/README.mdindex 26de34b..babbcbc 100644--- a/README.md+++ b/README.md@@ -13,7 +13,7 @@</p><p align="center">- <img src="docs/media/readme/watch-ray.webp" width="380" alt="Ray on an Apple Watch">+ <img src="docs/media/readme/watches.webp" width="720" alt="Three Apple Watches: Noodle, Ray and Tangle"></p><p align="center">diff --git a/bin/chums-claude b/bin/chums-claudeindex 3b325d4..def5aff 100755--- a/bin/chums-claude+++ b/bin/chums-claude@@ -52,8 +52,12 @@ EOFconfigs=(--mcp-config "$MCP_JSON")[[ -f ./.mcp.json ]] && configs+=(--mcp-config ./.mcp.json)+# Remote Control needs a claude.ai login: off with "remoteControl": false in ~/.chums/config.json (an API key), or+# CHUMS_NO_RC=1 for this sessionrc=(--remote-control)[[ -n "$CHUMS_NO_RC" ]] && rc=()+node -e 'process.exit(JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).remoteControl === false ? 0 : 1)' \+ ~/.chums/config.json 2>/dev/null && rc=()# Speaking to the watch is always allowed; a reply that waits on an approval would never be heard.exec command claude "${configs[@]}" "${rc[@]}" --settings "$HOOKS_JSON" \diff --git a/bin/chums-install b/bin/chums-installindex 0d61844..dcafbbb 100755--- a/bin/chums-install+++ b/bin/chums-install@@ -142,10 +142,10 @@ elseecho "Chums is installed on $PNAME."; breakfiecho "iPhone install attempt $i failed ($(grep -m1 -o 'ERROR: [^(]*' "$ILOG" || tail -1 "$ILOG")); unlock the iPhone"- [[ $i == 3 ]] && echo "Skipping the iPhone app. Full log: $ILOG"+ [[ $i == 3 ]] && { echo "The iPhone app didn't install. Full log: $ILOG"; PHONE_FAILED=1 }sleep 4donefi-[[ -n "$WATCH_FAILED" ]] && exit 1+[[ -n "$WATCH_FAILED" || -n "${PHONE_FAILED:-}" ]] && exit 1echo "Next: start the agents (bin/chums-agents install; docs/setup.md, step 10), and check the whole chain with bin/chums-doctor."diff --git a/bin/chums-setup b/bin/chums-setupindex 3890c1a..5fa7cee 100755--- a/bin/chums-setup+++ b/bin/chums-setup@@ -66,7 +66,7 @@ elif [[ -x $KPY ]] && "$KPY" -c 'import mlx_audio, misaki' 2>/dev/null; thenok "agents' voices (Kokoro, ~/.chums/kokoro)"elif command -v uv >/dev/null; thenprint " ... installing the agents' voices (Kokoro: its Python in ~/.chums/kokoro, about 1.1 GB; its model, about 0.35 GB)"- mkdir -p ~/.chums/kokoro+ mkdir -p -m 700 ~/.chums; mkdir -p ~/.chums/kokoro # ~/.chums is yours alone (the hub keeps it so too)if uv venv -q --python 3.12 ~/.chums/kokoro/.venv && uv pip install -q --python "$KPY" -r "$ROOT/tools/kokoro-requirements.txt" \&& (cd ~/.chums/kokoro && "$KPY" "$ROOT/tools/kokoro-server.py" --once --voices english >/dev/null 2>&1)then touch ~/.chums/kokoro/.voices-english; ok "agents' voices (Kokoro, ~/.chums/kokoro)"diff --git a/docs/media/readme/watch-ray.webp b/docs/media/readme/watch-ray.webpdeleted file mode 100644index e032446..0000000Binary files a/docs/media/readme/watch-ray.webp and /dev/null differdiff --git a/docs/media/readme/watches.webp b/docs/media/readme/watches.webpnew file mode 100644index 0000000..3bcbd91Binary files /dev/null and b/docs/media/readme/watches.webp differdiff --git a/docs/setup.md b/docs/setup.mdindex ee8ff4e..74810f2 100644--- a/docs/setup.md+++ b/docs/setup.md@@ -86,7 +86,7 @@ the watch or the iPhone in step 10.| Where it runs | In the background (`bin/chums-agents install`), or in a terminal (`bin/chums-agents open <id>`) | Inside the hub, started with it || Where you see it on the Mac | Its terminal, and the Claude app (Remote Control) | A Codex terminal on the same thread: `bin/chums-codex <id>` || In `~/.chums/agents.json` | `"runtime": "claude"`, or no `runtime` | `"runtime": "codex"` |-| Notes | Channels are a research preview. Team and Enterprise plans: an Owner enables channels (and Remote Control) in the organization's Claude Code settings. Remote Control needs a claude.ai login; with an API key, set `CHUMS_NO_RC=1` (export it before `bin/chums-agents install`, which keeps it for the background agents) | OpenAI labels the app-server experimental; Chums was written against 0.160. If Codex's default model isn't on your plan, set `"model"` |+| Notes | Channels are a research preview. Team and Enterprise plans: an Owner enables channels (and Remote Control) in the organization's Claude Code settings. Remote Control needs a claude.ai login; with an API key, set `"remoteControl": false` in `~/.chums/config.json` | OpenAI labels the app-server experimental; Chums was written against 0.160. If Codex's default model isn't on your plan, set `"model"` |Changing an agent's soul by voice (its name, what it looks after, its voice) runs `claude -p` on the Mac, so that onefeature needs Claude Code even when all your agents are Codex agents. A change typed on the iPhone doesn't.@@ -332,7 +332,7 @@ cd ~/some/project && /path/to/chums/bin/chums-claude <id>`<id>` is one of the ids above: the watch and the iPhone talk only to the agents in `agents.json`, and a session is anagent's when its name is the agent's id. `bin/chums-claude` adds the Chums channel and hooks, keeps Remote Control on-(`CHUMS_NO_RC=1` turns it off), keeps the project's own `.mcp.json`, and lets the session call `chums_reply` and read+(`"remoteControl": false` in `~/.chums/config.json` turns it off), keeps the project's own `.mcp.json`, and lets the session call `chums_reply` and readthe files you send from the iPhone (`~/.chums/uploads`) without asking. Itsfirst start shows the two screens above; answer them in the terminal.@@ -624,7 +624,7 @@ Each one is an environment variable, or a key in `~/.chums/config.json`, or the| `CHUMS_NODE` | `node` | `node` on your PATH | The node binary LaunchAgents run || `CHUMS_WHISPER_MODEL` | | `~/Documents/huggingface/models/argmaxinc/whisperkit-coreml/openai_whisper-base` | Whisper model folder || `CHUMS_CLAUDE_BIN` | | `claude` in `~/.local/bin`, `~/.npm-global/bin` or PATH | The claude CLI for the soul editor |-| `CHUMS_NO_RC` | | unset | Set to `1` to start Claude Code sessions without Remote Control (set when `bin/chums-agents install` runs, it is kept for the background agents) |+| `CHUMS_NO_RC` | `remoteControl` | on | `"remoteControl": false` starts every Claude Code session without Remote Control (for an API key); `CHUMS_NO_RC=1` does it for the sessions started from that shell || | `tts` | `{ "engine": "kokoro" }` when installed | The voice replies are read in: `kokoro` (each agent's own), `say` (a macOS voice), `openai`, or `watch` || `DEVELOPER_DIR` | | `/Applications/Xcode.app/Contents/Developer` | The Xcode the scripts use |diff --git a/hub/hub.mjs b/hub/hub.mjsindex 42d742d..59a1be8 100755--- a/hub/hub.mjs+++ b/hub/hub.mjs@@ -1374,6 +1374,8 @@ const setRuntime = (id, runtime) => serially(async () => {if (!available().includes(runtime)) throw Object.assign(new Error(`${runtime === 'codex' ? 'Codex' : 'Claude Code'} isn't installed on this Mac`), { code: 409 })const was = a.runtime ?? 'claude'if (was === runtime) return { id, runtime }+ // as it was, to go back to if the new runtime doesn't start+ const before = JSON.parse(JSON.stringify({ runtime: a.runtime, sessionId: a.sessionId, model: a.model, byRuntime: a.byRuntime }))a.byRuntime ??= {}a.byRuntime[was] = { ...(a.sessionId ? { sessionId: a.sessionId } : {}), ...(a.model ? { model: a.model } : {}) }const back = a.byRuntime[runtime] ?? {}@@ -1389,8 +1391,19 @@ const setRuntime = (id, runtime) => serially(async () => {else { runners.get(id)?.stop(); runners.delete(id) }const old = sessionOf(id)if (old) { sessions.delete(old.id); for (const [rid, x] of approvals) if (x.sessionId === old.id) approvals.delete(rid) }- if (runtime === 'claude') await run(AGENTS_BIN, ['add', id], 120_000)- else runners.set(id, startRunner(a, runtimeHub))+ try {+ if (runtime === 'claude') await run(AGENTS_BIN, ['add', id], 120_000)+ else runners.set(id, startRunner(a, runtimeHub))+ } catch (e) {+ // it didn't start: the agent goes back to what it ran on, and runs there again+ log(`${id}: couldn't start on ${runtime} (${e.message}); back on ${was}`)+ for (const k of Object.keys(before)) { if (before[k] === undefined) delete a[k]; else a[k] = before[k] }+ saveAgents()+ if (was === 'claude') await run(AGENTS_BIN, ['add', id], 120_000).catch(e2 => log(`${id}: restarting it on Claude Code: ${e2.message}`))+ else runners.set(id, startRunner(a, runtimeHub))+ bump()+ throw Object.assign(new Error(`${id} couldn't start on ${runtime === 'codex' ? 'Codex' : 'Claude Code'}: ${e.message}`), { code: 500 })+ }log(`${id}: now on ${runtime}`); bump()return { id, runtime }})diff --git a/tools/doctor.py b/tools/doctor.pyindex 00099d4..ec8becb 100644--- a/tools/doctor.py+++ b/tools/doctor.py@@ -1,6 +1,7 @@"""Checks the whole Chums chain on this Mac and prints a pass/fail list, with the fix for each failure.-Run it as bin/chums-doctor. It is read-only: it starts, stops, writes and installs nothing. What it does:+Run it as bin/chums-doctor. It is read-only: it starts, stops, changes and installs nothing (devicectl's list of+devices passes through a temporary file). What it does:- runs version and sign-in checks (`claude auth status`, `codex login status`, `xcodebuild -version`, ...);- reads ~/.chums/config.json and ~/.chums/agents.json;- asks the hub for /v1/ping and /v1/state on 127.0.0.1, and the Funnel URL for /v1/ping over HTTPS;@@ -207,7 +208,7 @@ if claude:ok(f'Claude Code {cv}, signed in ({method}){where}')if method != 'claude.ai':note('Remote Control (the session also showing in the Claude app) needs a claude.ai login; '- 'with an API key, start sessions with CHUMS_NO_RC=1')+ 'with an API key, set "remoteControl": false in ~/.chums/config.json')else:(fail if need_claude else warn)(f'Claude Code {cv} is installed but not signed in{where}','run claude, then /login (a Pro, Max, Team or Enterprise plan, or a Console API key)')@@ -447,16 +448,15 @@ if url and cfg and cfg.get('watchToken'):fail(f'{name} does not resolve in public DNS yet',['a new Funnel name takes a while: Tailscale says up to 10 minutes; it has taken about 25','run bin/chums-doctor again later; nothing else to do'])- code, body = None, ''- with tempfile.NamedTemporaryFile() as tmp:- t0 = time.time()- rc, out, err = run(['curl', '-sS', '--max-time', '15', '-o', tmp.name, '-w', '%{http_code} %{remote_ip}',- '-H', '@-', f'{url.rstrip("/")}/v1/ping'],- timeout=25, stdin=f'Authorization: Bearer {cfg["watchToken"]}\n')- took = time.time() - t0- parts = out.split()- code = parts[0] if parts else None- remote = parts[1] if len(parts) > 1 else ''+ # the answer's body isn't kept (read-only: nothing written, not even a temporary file)+ t0 = time.time()+ rc, out, err = run(['curl', '-sS', '--max-time', '15', '-o', '/dev/null', '-w', '%{http_code} %{remote_ip}',+ '-H', '@-', f'{url.rstrip("/")}/v1/ping'],+ timeout=25, stdin=f'Authorization: Bearer {cfg["watchToken"]}\n')+ took = time.time() - t0+ parts = out.split()+ code = parts[0] if parts else None+ remote = parts[1] if len(parts) > 1 else ''tailnet = Falsetry: tailnet = ipaddress.ip_address(remote) in ipaddress.ip_network('100.64.0.0/10') or remote.startswith('fd7a:115c:a1e0')except ValueError: pass@@ -556,10 +556,13 @@ section('7. The Apple Watch (as Xcode sees it)')if not xcode_ok:note('skipped: Xcode is needed to see devices')else:- with tempfile.NamedTemporaryFile(suffix='.json') as tmp:- rc, out, err = run(['xcrun', 'devicectl', 'list', 'devices', '--json-output', tmp.name], timeout=60, env={'DEVELOPER_DIR': DEV})- try: devices = json.load(open(tmp.name))['result']['devices']- except (ValueError, KeyError, OSError): devices = None+ devices, rc, out, err = None, 1, '', ''+ try: # devicectl writes its list only to a file+ with tempfile.NamedTemporaryFile(suffix='.json') as tmp:+ rc, out, err = run(['xcrun', 'devicectl', 'list', 'devices', '--json-output', tmp.name], timeout=60, env={'DEVELOPER_DIR': DEV})+ try: devices = json.load(open(tmp.name))['result']['devices']+ except (ValueError, KeyError, OSError): devices = None+ except OSError as e: err = f'no temporary file for its list: {e}'if devices is None:fail(f'xcrun devicectl could not list devices ({(err or out).splitlines()[-1] if (err or out) else rc})', 'open Xcode once and try again')else: