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 |
Watch for needs_input when a session needs your attention. Terminal bell alerts depend on your client and its notification settings. For native mobile push notifications, see the mobile setup guide.
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 |
3 |
Conversations — browse and resume past threads |
? |
Full keymap |
Resume a past conversation
Press 3 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.
Help improve ccmux
Found a bug, an unclear guide, or a translation that could read better? Contributions of any size are welcome. Open an issue or send a pull request.
Spotted an error or something out of date? Edit this page on GitHub.