Skip to content

armgit / chums

Public Imported from GitHub
0

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.md
index 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-claude
index 3b325d4..def5aff 100755
--- a/bin/chums-claude
+++ b/bin/chums-claude
@@ -52,8 +52,12 @@ EOF
configs=(--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 session
rc=(--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-install
index 0d61844..dcafbbb 100755
--- a/bin/chums-install
+++ b/bin/chums-install
@@ -142,10 +142,10 @@ else
echo "Chums is installed on $PNAME."; break
fi
echo "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 4
done
fi
-[[ -n "$WATCH_FAILED" ]] && exit 1
+[[ -n "$WATCH_FAILED" || -n "${PHONE_FAILED:-}" ]] && exit 1
echo "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-setup
index 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; then
ok "agents' voices (Kokoro, ~/.chums/kokoro)"
elif command -v uv >/dev/null; then
print " ... 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.webp
deleted file mode 100644
index e032446..0000000
Binary files a/docs/media/readme/watch-ray.webp and /dev/null differ
diff --git a/docs/media/readme/watches.webp b/docs/media/readme/watches.webp
new file mode 100644
index 0000000..3bcbd91
Binary files /dev/null and b/docs/media/readme/watches.webp differ
diff --git a/docs/setup.md b/docs/setup.md
index 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 one
feature 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 an
agent'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 read
the files you send from the iPhone (`~/.chums/uploads`) without asking. Its
first 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.mjs
index 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.py
index 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 = False
try: 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: