Real-time web dashboard for monitoring and controlling multiple Claude Code sessions
Features • Installation • Quick Start • CLI • Architecture
Dashboard — sessions grouped by project with live state indicators
Session view — real-time ANSI terminal output with action toolbar
Mobile
Fully responsive — control sessions from your phone
- 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 - Mobile-first — touch toolbar, hamburger sidebar, swipe gestures
- 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
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 -lFrom source
git clone https://github.com/christinoleo/claude-mux.git
cd claude-mux
bun install && bun run build
bun link # makes 'claude-mux' available globallyclaude-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.
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
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.
# 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 automatically| 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) |
Claude Code events ──> Hook script ──> JSON files (~/.claude-mux/sessions/)
|
File watcher (500ms)
|
WebSocket broadcast
|
Browser <──> SvelteKit server
Hooks 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.
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.
- 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
MIT
PRs welcome. Fork, branch, test (bun test), and open a PR.