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 |
blue | The agent finished, no prompt visible |
needs_input |
yellow | The agent is showing its input box, quiet for ≥ 3s |
error |
red | The agent exited or crashed and left you at a shell prompt, even if its last screen is still showing |
Sessions you start in tmux yourself show as plain shells, unless an agent is running in them. Every session ccmux starts keeps the agent it started with, even if you later switch the project’s agent.
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 |
/ |
Filter by name, project, host, or agent (Enter attaches to the highlighted match, Esc clears) |
3 |
Conversations — browse and resume past threads |
? |
Full keymap |
Resume a past conversation
Press 3 to open the Conversations screen. It lists every past thread on disk from Claude Code, Codex, Cursor and more, newest first. 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. From a shell it’s ccmux attach --host mini my-project, for any host you added with ccmux host add.
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? Open an issue on GitHub.