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, or Ctrl+\`` while the input is focused; press Enterto 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 /rc and 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, capture commands 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 | bash

Override 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 hooks

If 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 -l

git clone https://github.com/christinoleo/claude-mux.git
cd claude-mux
bun install && bun run build
bun link  # makes 'claude-mux' available globally

Updating

claude-mux update           # npm i -g latest, re-syncs hooks, restarts prod server if running
claude-mux update --force   # reinstall even when already on latest

update 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 boot

Logs: 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.service

Edit the file then systemctl --user restart claude-mux.service to pick up changes.

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 automatically

CLI 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 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.

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.