Integration guide
bubble-wand exposes each Claude Code session running in your tmux to the Bubbles watch app — so from your wrist you can see which sessions need you, read a summary, dictate a reply by voice, and tap through menus. Your Anthropic key and your code never leave your machine.
A "thread" on your wrist is a tmux pane running claude
on your box. The bridge reads and writes those panes directly
(tmux capture-pane / send-keys) — so it must run
on the same machine as your Claude Code sessions. That constraint is the privacy model: no server
in the middle, no shared multi-tenant host, and no one else ever holds your key.
This is for people who run their own Claude Code sessions in tmux. It is not a hosted SaaS and not turnkey for non-developers — and that's deliberate.
A short list. If you already run Claude Code in tmux on an always-on box, you have most of it.
claude panes in one window
a machine that stays on
your own Anthropic API key (sk-ant-…)
One command bootstraps everything — clone, virtualenv, dependencies, and a systemd user service — then prints a one-time setup URL.
curl -fsSL https://get.darn-tech.com/install.sh | bash
or clone it yourself —
git clone https://github.com/GreenTilden/bubble-wand
cd bubble-wand
./install.sh
fastapi,
uvicorn, anthropic).--user service
(clawatch-bridge, bubble-wand's engine) with lingering enabled — it starts
on boot and keeps running after you log out.http://<your-box-LAN-IP>:8793/setup?t=<one-time-code>/setup page writes it (and the token) to a 0600
file and applies it live, no restart needed.Prefer to run it without systemd?
CLAWATCH_NO_SERVICE=1 ./install.sh prints the exact
uvicorn command instead.
By default the bridge reads panes in the tmux target dev:1 —
session named dev, window 1. Each pane in that
window becomes one thread on your wrist.
tmux new-session -s dev # a session called "dev"
# in window 1, split into panes and run `claude` in each:
tmux split-window -h # pane 2
tmux split-window -v # pane 3, etc.
# run your Claude Code sessions in those panes
Point the bridge at wherever your Claude Code panes actually live by setting
CLAWATCH_TMUX_WINDOW (e.g. work:2). The bridge
derives each thread's status — working, needs input, or idle — from the pane, and
surfaces the ones needing you first.
Config is read from the environment (the installer writes it to
clawatch.env). Secrets are added by /setup, not by hand.
| Variable | Default | What it does |
|---|---|---|
CLAWATCH_HOST | 0.0.0.0 | Bind address. 0.0.0.0 lets any device on your LAN reach it; set a specific LAN IP to restrict it. |
CLAWATCH_PORT | 8793 | Port to listen on. |
CLAWATCH_TMUX_WINDOW | dev:1 | The tmux window whose panes are your Claude Code threads. |
ANTHROPIC_API_KEY | (unset) | Your key. Written by /setup. Powers voice-suggestion features; when unset those simply return empty. |
CLAWATCH_TOKEN | (minted) | Bearer token required on every /api call. Minted by /setup; pin it yourself to keep it stable. |
CLAWATCH_TAIL_LINES | 40 | Default number of recent lines returned per thread. |
CLAWATCH_SUGGEST_MODEL | claude-haiku-4-5-20251001 | Model used for wrist reply suggestions (uses your key). |
CLAWATCH_SUGGEST_MAX_TOKENS | 150 | Cap on suggestion output. |
Restart after editing config:
systemctl --user restart clawatch-bridge.
The bridge is LAN-first — the simplest, safest setup is the watch and the bridge on the same network. To reach your sessions from cellular or away from home, front the bridge with a named Cloudflare Tunnel.
Runs on this box and publishes a stable hostname — no inbound ports and no firewall changes on your end.
Once you expose it, the bearer token is your only guard. Treat the tunnel hostname as a secret too.
Onboarding (/setup) is refused over a tunnel or proxy on purpose — set it up locally, then expose the already-configured bridge.
The bridge sits next to live shells, so every surface is locked down by design.
Written to a 0600 file by /setup and sent only to Anthropic, on your behalf. No telemetry, ever.
Every tmux call uses an argv list (shell=False) — no shell, no interpolation. The pane target is an integer index verified against the live pane list, so no client string reaches the tmux -t argument.
Sends use send-keys -l -- <text> (literal) then a separate Enter, so control sequences in a voice reply (C-c, ;kill-server) are typed as plain characters, never run.
Every /api route requires Authorization: Bearer <token> (constant-time compare). Soft keys are an allowlist, never a raw key name.
/setup works only from loopback/private addresses, only with the one-time code, and only while unconfigured; any proxy/tunnel hop or a provisioned bridge is rejected.
All /api routes require
Authorization: Bearer <CLAWATCH_TOKEN>.
index is the integer pane index (1..N), verified
against the live pane list.
| Endpoint | Notes |
|---|---|
GET /healthz | Liveness, no auth → {"ok": true} |
GET /api/threads | List panes as threads with derived status |
GET /api/threads/{index}/tail | Recent output + any parsed menu prompt. Query: lines=40&scrollback=false |
POST /api/threads/{index}/send | Body {"text":"…","submit":true} — dictated reply |
POST /api/threads/{index}/key | Body {"action":"escape|interrupt|clear|enter"} |
POST /api/threads/{index}/suggest | Haiku-generated reply suggestions (needs your key; else []) |
GET /api/usage | Suggestion token/cost tally |
GET /setup · POST /api/setup | One-time LAN onboarding |
TOKEN=... # the token from /setup
BASE=http://<your-box-LAN-IP>:8793
curl -s $BASE/healthz
curl -s -H "Authorization: Bearer $TOKEN" $BASE/api/threads | jq
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/threads/1/tail?lines=20" | jq
systemctl --user status clawatch-bridge # is it running?
systemctl --user restart clawatch-bridge # after a config change
journalctl --user -u clawatch-bridge -f # live logs
To re-provision with a different key: clear
ANTHROPIC_API_KEY / CLAWATCH_TOKEN from
clawatch.env and restart — /setup becomes
available again.
clawatch-bridge is the server half. The client is
Bubbles, a Wear OS app that lists your threads, shows live status, reads the tail, and takes voice
replies. Install it on your watch and enter the URL + token from /setup in its
Settings.
In invite-only testing now; a public Play Store listing is on the way. The bridge is free and open source — start there.