# ccmux

> Persistent, self-healing Claude Code sessions in tmux

One daemon per machine keeps long-running Claude Code agent sessions alive in tmux — healing crashes, restoring them on reboot and resuming the same conversation by a pinned uuid.

- Repository: https://github.com/max-listov/ccmux
- License: MIT
- Language: TypeScript
- Platforms: macOS (launchd) and Linux (systemd), plus tmux

## Install

```bash
curl -fsSL https://github.com/max-listov/ccmux/releases/latest/download/install.sh | bash
```

Installs Bun if missing, downloads the latest verified bundle, puts a `ccmux` shim on
PATH and starts a self-updating daemon. Re-running is safe — it refreshes to the latest release.

## What it does

Sessions are full interactive `claude` processes using your own subscription, with slash
commands and statusline intact. ccmux supervises them; it does not reimplement them.

- **One daemon per machine** under launchd or systemd heals the fleet every 30 seconds
  and brings it back on boot.
- **A supervisor per session** relaunches the agent on crash with exponential backoff.
  Killing the session is the only way to stop it.
- **Deterministic resume** — each session pins a fixed uuid, so a restart continues the
  same conversation. Blocking resume prompts are answered automatically so an unattended
  heal never stalls at a menu.
- **Follow the fork** — running out of context makes Claude fork the conversation to a new
  session id; each heal pass detects the move and re-pins the registry.
- **jsonl is the source of truth** for history and token counts; the pane is scraped only
  for live status.

## Commands

```bash
ccmux                        # interactive fleet TUI
ccmux list                   # managed sessions with live status and uptime
ccmux new cc-api ~/code/api  # create and start a session
ccmux send cc-api '/compact' # type into a session
ccmux restart cc-api         # bounce it, survives killing the caller
ccmux transcript cc-api --json
ccmux doctor                 # health check: binaries, config, daemon
```

Attach like any tmux pane: `tmux attach -t cc-api`, detach with `Ctrl-b d`.

## Permissions

Two levels: a machine default plus an optional per-session override. Under a root daemon,
escalated modes are downgraded to `auto` at launch — from either source — so a config edit
cannot hand a server session host-wide power.

## Inter-agent chat

Opt-in messaging between managed sessions, off by default on both ends. Messages can be
deferred until the recipient voluntarily finishes its turn, or armed on a timer.

## When not to use it

- You run one session occasionally — plain tmux plus `claude` is enough.
- Windows without WSL: the daemon is launchd or systemd only.
- You want a hosted web UI — there is no server component.

## Documentation

- [ccmux](https://maxlistov.com/ccmux/docs/readme.md)
- [Changelog](https://maxlistov.com/ccmux/docs/changelog.md)

---

Author: Max Listov · https://maxlistov.com · maxlistov@gmail.com