claude-mux
v0.30.34
Published
Real-time web dashboard for monitoring and controlling multiple Claude Code sessions
Maintainers
Readme
Features
- Live session monitoring — WebSocket-powered, no polling. See state (busy/idle/waiting/permission) at a glance
- Project grouping — sessions organized by working directory with color-coded borders
- ANSI terminal rendering — real tmux colors via ansi_up, toggleable
- Session control — send text, keys (Up/Down/Tab/Esc/Ctrl-C), Yes/No/Always quick buttons
- Voice input — local Whisper transcription (CPU or CUDA, auto-detected). Trigger with
F2,Pause, orCtrl+\`` while the input is focused; pressEnterto stop and submit,Escor the×` overlay to discard. Long-press the mic button for language, microphone, and auto-submit settings - Orchestrator pairing — main + orchestrator sessions grouped together with role labels
- Remote Control — auto-detects Claude's
/rcand opens it in a new window - Phone notifications — Web Push when a session needs you or finishes, with claude-mux closed (see Push notifications)
- Mobile-first — touch toolbar, hamburger sidebar, swipe gestures
- Side panel — beside a session: what it changed, the project's files, and its site in a frame (see Project URLs)
- Screenshots panel — view and dismiss captured screenshots
- Dead pane detection — visual indication when a tmux pane closes
- Other tmux panes — browse and view non-Claude panes too
- Auth support — optional password protection for LAN access
- CLI scripting —
send,wait,status,capturecommands for automation
Installation
One-liner (recommended) — installs bun, claude-mux, hooks, and starts the server on 127.0.0.1:3456:
curl -fsSL https://raw.githubusercontent.com/christinoleo/claude-mux/main/scripts/install.sh | bashOverride defaults with env vars: CLAUDE_MUX_VERSION, CLAUDE_MUX_PORT, CLAUDE_MUX_NO_SETUP=1, CLAUDE_MUX_NO_SERVE=1.
Manual — if you already have a Node/Bun toolchain:
npm install -g claude-mux # or: bun install -g claude-mux
claude-mux setup # install Claude Code hooksIf npm install -g fails with EACCES, your npm prefix is a system path. Switch to a user prefix (one-time):
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
exec $SHELL -lgit clone https://github.com/christinoleo/claude-mux.git
cd claude-mux
bun install && bun run build
bun link # makes 'claude-mux' available globallyUpdating
claude-mux update # npm i -g latest, re-syncs hooks, restarts prod server if running
claude-mux update --force # reinstall even when already on latestupdate stops the prod server before reinstalling so live module files aren't clobbered, then re-runs setup --yes so hook paths stay current.
Running as a service (boot autostart)
claude-mux service install writes a systemd user unit (no root needed for install):
claude-mux service install # writes ~/.config/systemd/user/claude-mux.service, enables + starts
claude-mux service status # systemctl --user status …
claude-mux service uninstall --purge # disable + remove unit
sudo loginctl enable-linger $USER # ONE-TIME sudo: keeps service running after logout / starts on bootLogs: journalctl --user -u claude-mux.service -f
Secrets / API keys (Groq voice, etc.)
The unit reads ~/.config/claude-mux/env if present (EnvironmentFile=-). Put any KEY=value env vars there — they survive restarts and stay out of the unit file. Voice transcription needs GROQ_API_KEY:
umask 077
mkdir -p ~/.config/claude-mux
printf 'GROQ_API_KEY=gsk_...\n' > ~/.config/claude-mux/env
systemctl --user restart claude-mux.serviceEdit the file then systemctl --user restart claude-mux.service to pick up changes.
Push notifications (phone)
The server can notify a phone, tablet or desktop browser when a session asks a question, wants an approval, or finishes its turn, even with every claude-mux tab closed. The server watches the sessions itself and sends through the browser's push service (Web Push with VAPID), so nothing needs to stay open on the device.
It needs HTTPS. Browsers only allow service workers and push on a secure origin (localhost aside). The simplest way is tailscale serve, which puts a certificate in front of the local server:
tailscale serve --bg --https=8443 http://127.0.0.1:3456
# then open https://<machine>.<tailnet>.ts.net:8443 on the phoneTo turn it on for a device, open claude-mux there and choose Push → This device at the foot of the sidebar, then allow notifications. Two checkboxes pick the events (Needs you, Done), and Send a test checks the whole path.
- Android (Chrome): works from the browser tab or an installed app.
- iPhone / iPad (iOS 16.4+): Safari only offers push to web apps on the Home Screen. Open the HTTPS address in Safari, tap Share → Add to Home Screen, open claude-mux from the new icon, and turn push on from there.
Tapping a notification opens that session. A device with claude-mux open in front gets no push, because the page alerts for itself there (a toast, per the sidebar's settings).
The server keeps its VAPID key pair in ~/.claude-mux/vapid.json (made on first use) and the devices in ~/.claude-mux/push-subscriptions.json. Deleting the key file orphans every subscription; turn push off and on again on each device. A device the push service reports as gone (HTTP 404/410) is dropped automatically. Each claude-mux server pushes for its own sessions, so with several machines on the tailnet, turn push on once per machine's address.
Project URLs and icon (.claude-mux.json)
The session side panel's Web tab shows a project's site in a frame. Name the URLs in a .claude-mux.json committed at the repo root, so every machine sees the same:
{ "urls": { "prod": "https://example.com", "dev": "http://localhost:5173" } }Both keys are optional, and only http(s) URLs are read. With no dev, the tab looks for dev servers itself: TCP listeners whose process runs inside the project and answer HTTP with an HTML page (Linux only, through ss and /proc). Any URL can also be typed into the tab's bar.
A localhost URL means the phone itself when opened on the phone, and an HTTPS page cannot frame plain HTTP. So a dev server on this machine is framed through its tailscale serve HTTPS mapping when it has one; otherwise the tab offers it in a new tab, with the command that would make it embeddable:
tailscale serve --bg --https=5173 http://localhost:5173A site that forbids framing (X-Frame-Options, or a CSP frame-ancestors that leaves claude-mux out) gets an "Open in new tab" card rather than a blank frame.
The same file can name the project's icon, which the sidebar shows beside its name:
{ "icon": "web/static/logo.svg", "urls": { "prod": "https://example.com" } }icon is a path from the repo root (it cannot climb out of it) or an http(s) URL. Without one, claude-mux looks for the repo's own icon: favicon.svg, favicon.png, favicon.ico, icon.svg, icon.png or apple-touch-icon.png in a static/, public/ or app/ folder or below one, taking an SVG first, then the widest PNG, then an ICO. Failing that it uses the favicon of the prod URL, and failing that the project is drawn as two letters of its name on a colour derived from the name, the same on every machine. The icon is read on the machine that holds the repo, and when several machines hold the project the first that has an icon gives it.
Quick Start
# 1. Install hooks into Claude Code
claude-mux setup
# 2. Start the web server
claude-mux serve --port 3456 --host 0.0.0.0
# 3. Open http://localhost:3456 (or your LAN IP)
# 4. Start any Claude Code session — it appears automaticallyCLI Commands
| Command | Description |
|---------|-------------|
| claude-mux serve | Start web server (--port, --host, --auth <password>) |
| claude-mux setup | Install Claude Code hooks |
| claude-mux update | npm i -g latest, re-sync hooks, restart prod server |
| claude-mux service install | Install systemd user unit (boot autostart, no root) |
| claude-mux service uninstall | Disable systemd user unit (--purge removes the file) |
| claude-mux service status | Show systemd service status |
| claude-mux uninstall | Remove hooks and configuration |
| claude-mux send <target> [text] | Send text or --keys to a session |
| claude-mux status <target> | Get session state as JSON |
| claude-mux wait <target> | Block until session reaches --state (default: idle,waiting,permission) |
| claude-mux new-session --cwd <path> | Spawn a new detached Claude Code session |
| claude-mux capture <target> | Capture tmux pane output (--lines N) |
| claude-mux | TUI dashboard (legacy, requires tmux) |
How It Works
Claude Code events ──> Hook script ──> JSON files (~/.claude-mux/sessions/)
|
File watcher (500ms)
|
WebSocket broadcast
|
Browser <──> SvelteKit serverHooks run inside Claude Code's process and write session state to JSON on every event (start, prompt, tool use, stop, notification). The SvelteKit server watches those files and pushes updates to connected browsers via WebSocket. Terminal output is captured directly from tmux panes.
Troubleshooting
Sessions not appearing — Run claude-mux setup, then restart Claude Code sessions (hooks load at startup).
Can't connect from another device — Use --host 0.0.0.0 and check your firewall.
Status not updating — Verify hooks: grep claude-mux ~/.claude/settings.json
Voice transcription slow on first use — The first invocation builds whisper.cpp and downloads a Whisper model into ~/.claude-mux/voice/. Subsequent runs reuse the cache. CUDA is used automatically if nvidia-smi and nvcc are present.
Requirements
- Bun >= 1.0
- tmux
- Claude Code with hooks support
- Optional, for voice input: a working C/C++ toolchain (whisper.cpp builds on first use); NVIDIA CUDA toolkit for GPU transcription
License
MIT
Contributing
PRs welcome. Fork, branch, test (bun test), and open a PR.
