The normal case
handled by supervisorA tmux session whose foreground process is a small supervisor loop. It launched claude and is watching it. The conversation is pinned to a fixed uuid, and its history is written to a jsonl transcript.
[ open source · MIT ]
ccmux
Persistent, self-healing Claude Code sessions in tmux
A single daemon per machine keeps a fleet of long-running agent sessions alive: it heals crashed ones, brings them back on reboot, and resumes the same conversation by a pinned uuid. Sessions are full interactive claude processes — ccmux supervises them, it does not reimplement them.
curl -fsSL https://github.com/max-listov/ccmux/releases/latest/download/install.sh | bashRequires macOS (launchd) or Linux (systemd), plus tmux.
- Version
- v0.1.19
- Commits
- 43
- Last commit
- 25 Jul 2026
- License
- MIT
The whole fleet from one CLI
Pick a command to see what it actually prints. These are real outputs, taken from a running install — not mock-ups.
$ccmux list
SESSION MODEL CTX STATE UPTIME RC DIR cc-api Opus 5 890.0k/1.0M 89% working 16m prod-api ~/code/api cc-web Opus 5 420.0k/1.0M 42% idle 3d11h prod-web ~/code/web cc-infra Opus 5 740.0k/1.0M 74% idle 3d20h prod-infra ~/infra cc-docs Opus 4.8 100.0k/1.0M 10% waiting 3d20h prod-docs ~/code/docs
Context left, state and uptime per session. Note the uptime in days — these survive reboots.
$ccmux new cc-api ~/code/api
added: cc-api|/root/code/api|27e0665f-5ecc-4e67-b840-f32c49f2c791 started cc-api (prod-api)
A fixed uuid is pinned right away — every later resume uses it, so there is no session picker to get stuck on.
$ccmux send cc-api '/compact'
sent to cc-api: /compact
Text or a slash command lands in the pane as if typed by hand. This is what makes scripts and hooks possible.
$ccmux restart cc-api
restarting cc-api stopped cc-api started cc-api (prod-api) — resumed 27e0665f
Survives killing the caller — an agent can restart itself and come back to the same conversation.
$ccmux transcript cc-api --json --tail 2
{"seq":841,"role":"user","kind":"text","createdAt":"2026-07-28T21:14:03Z",
"text":"check why the deploy failed"}
{"seq":842,"role":"assistant","kind":"tool_use","name":"Bash",
"input":{"command":"journalctl -u api -n 50"},
"resultText":"Jul 28 21:12:44 api[1180]: FATAL: password authentication failed"}Structured messages with tool calls and their results, read from the jsonl transcript — not scraped off the screen.
$ccmux doctor
ccmux 0.1.19 self: /root/.bun/bin/bun /root/.ccmux/app/ccmux.js config: /root/.config/ccmux/machine.json sessions: /root/.ccmux-sessions rc prefix: prod boot label: ccmux.service claude: /root/.local/bin/claude (ok) codex: /usr/bin/codex (ok) tmux: /usr/bin/tmux (ok) daemon: active (systemd)
The first thing to ask when a machine's fleet behaves oddly.
$ccmux msg cc-web 'schema is ready' --defer
queued for cc-web (deferred until it finishes its turn)
Hand work from one agent to another without relaying it yourself. Off by default on both ends.
How it stays alive
Six situations a long-running agent session actually meets. Pick one to see what happens and who handles it.
The agent dies, the session does not
handled by supervisorThe supervisor notices the process is gone and relaunches it with exponential backoff, resuming the pinned uuid. From the outside it looks like a pause, not a loss. Killing the tmux session is the only way to actually stop it.
Everything comes back on boot
handled by daemonOne daemon per machine is registered with launchd or systemd. On boot it re-creates every managed session; between boots it re-checks the fleet every 30 seconds and heals whatever is missing.
Follow the fork
handled by daemonClaude itself does not keep a uuid forever: running out of context forks the conversation into a new session id with a new jsonl. Each heal pass detects that the conversation moved and re-pins the registry, so transcripts and the next restart follow the live conversation instead of a dead file.
Nobody is there to press Enter
handled by supervisorLarge or old sessions get a blocking "resume from summary?" prompt. An unattended heal would strand at that menu, and input would land on the menu instead of the conversation. The supervisor answers it automatically according to the machine config.
The only way out
handled by youAn explicit stop or rm ends the session — the daemon does not resurrect it. The jsonl history stays on disk, so a removed session can be brought back later with adopt by its uuid.
Built for a fleet, not one laptop
Two-level permissions
A machine default plus an optional per-session override. Under a root daemon, escalated modes are downgraded at launch — a config edit cannot hand a server session host-wide power.
Inter-agent chat
Opt-in messaging between managed sessions, so one agent hands off to another without you relaying. Messages can be deferred until the recipient finishes its turn, or armed on a timer.
Adopt external sessions
A claude you started by hand shows up as external. Fork it into a safe copy, or take over the original.
Self-updating fleet
Releases are born only from tags, in CI. Machines pick up the verified bundle on their own — and sessions survive the update.
Requirements
- Operating system
- macOS or LinuxThe daemon runs under launchd or systemd.
- Required
- tmuxEvery session is a tmux session; attach to it like any other pane.
- Runtime
- BunInstalled automatically by the install script if missing.
- Agent backend
- claude · codexSessions are real interactive processes using your own subscription.
- Install
- One commandDownloads the verified release bundle and starts a self-updating daemon.
- License
- MIT
When to reach for it — and when not to
Good fit
- Agent sessions that must survive crashes, reboots and days of uptime
- Several machines running long-lived Claude Code sessions at once
- Driving a session by name from scripts and hooks instead of by hand in tmux
- Handing a task from one agent session to another without relaying it yourself
Look elsewhere
- You run one session, occasionally
- Plain tmux plus claude does that fine. ccmux earns its place when sessions are long-lived and there are several of them.
- You are on Windows without WSL
- The daemon is launchd or systemd, and everything sits on tmux. macOS and Linux only.
- You want a hosted web UI
- ccmux supervises local processes on your own machines. There is no server component and no dashboard to log into.
- You expect it to replace Claude Code
- Sessions are ordinary interactive claude processes with your subscription, slash commands and statusline. ccmux keeps them alive — it does not reimplement them.
Frequently asked
What happens to my session when Claude Code crashes?
It comes back. The foreground process of each tmux session is a small supervisor loop that relaunches the agent with exponential backoff, so a crash is just a pause. Killing the tmux session is the only way to actually stop it.
Does it survive a reboot?
Yes. One daemon per machine is registered with launchd or systemd, starts on boot and re-creates every managed session within about thirty seconds.
Do I lose the conversation when a session restarts?
No. Every session pins a fixed uuid — created once, resumed after — so a restart continues the same conversation instead of opening a new one. There is no session picker to get stuck on, and blocking resume prompts are answered automatically so an unattended heal never stalls at a menu.
What is 'follow the fork'?
When Claude runs out of context it forks the conversation into a new session id, leaving the old transcript behind. Each heal pass detects that the conversation moved and re-pins the registry, so transcripts and the next restart follow the live conversation rather than a dead file.
Is it safe to run on a shared server?
There is a root guard: under a root daemon, escalated permission modes are downgraded to auto at launch — whether they came from the machine default or a per-session override. A config edit cannot hand a server session host-wide power.
Can two agent sessions talk to each other?
Yes, and it is off by default. Enable chat per session, then one session can message another; messages can be deferred until the recipient voluntarily finishes its turn, or armed on a timer. Nothing is sent or received until both ends opt in.
Can I still use plain tmux commands?
Yes. Sessions live on the default tmux socket, so tmux attach, tmux ls and detaching with Ctrl-b d all work as usual. ccmux supervises them; it does not hide them behind a custom protocol.