Tutorial 2: Juggling Multiple Sessions
You have three projects moving in parallel. Open the TUI:
ccmux
Session states
The Home screen shows all sessions, color-coded:
| State | Color | Meaning |
|---|---|---|
active | green | The agent is generating output right now |
idle | yellow | The agent finished, no prompt visible |
needs_input | red | The agent is showing its input box, quiet for ≥ 3s |
needs_input is the one to watch. When any session transitions to it, ccmuxd injects a terminal BEL — any iOS terminal client that maps BEL to a notification raises a push.
Attach, work, detach
Navigate to a session with j / k, press Enter to attach. When you’re done, press Ctrl-b d — the ccmux TUI resumes automatically.
Useful keys on the Home screen
| Key | Action |
|---|---|
Enter | Attach to session |
x | Kill the highlighted session |
R | Rename |
k | Pin keep-awake (daemon holds caffeinate -s while pinned) |
2 | Conversations — browse and resume past threads |
? | Full keymap |
Resume a past conversation
Press 2 to open the Conversations screen. It lists every past Claude / Codex / Antigravity / Cursor / pi thread on disk, sorted by recency. Navigate with j / k and press Enter to resume — ccmux launches the agent with the right --resume flag and attaches.
Splitting work across machines
Start a session on your laptop and another on the Mini from the same dashboard — the Projects screen lets you pick which device hosts the new project (n → select device). The remote daemon starts the session; ccmux ssh-attaches you in.
Spotted an error or something out of date? Edit this page on GitHub.