How to Manage Multiple Claude Code Sessions with tmux
How to Manage Multiple Claude Code Sessions with tmux
Once you start running multiple Claude Code agents in parallel, the terminal tab situation gets out of control fast. Five tabs, all named "zsh", all running different agents on different parts of your codebase. You lose track of which agent is doing what. You accidentally close a tab and kill a session that was mid-refactor.
tmux fixes this completely.
Named Sessions
The key is naming each tmux session after the project and the task:
tmux new -s fazm-refactor
tmux new -s fazm-pipeline
tmux new -s autoposter-stats
Now tmux ls gives you a clear overview:
fazm-refactor: 1 windows (attached)
fazm-pipeline: 1 windows
autoposter-stats: 1 windows
You can see exactly what is running, attach to any session with tmux a -t fazm-pipeline, and detach without killing the process. Close your terminal, reopen it, everything is still running.
Branch Isolation
Each agent should work on its own git branch. This prevents the most common multi-agent disaster: one agent commits a half-done change, another agent pulls it, and now both agents are confused.
The pattern:
- Create a branch for each agent's task:
git checkout -b feat/refactor-capture-pipeline - Start the Claude Code session in that branch
- When the agent finishes, review and merge the branch
This also means you can easily discard an agent's work if it goes off track - just delete the branch.
Detach and Reattach
The real power of tmux is that sessions survive terminal disconnects. Start a long refactor, detach (Ctrl+B, D), go do something else, come back and reattach. The agent kept working the entire time.
This is especially useful for overnight tasks. Start three agents before bed, each working on a different module. Check the results in the morning.
Quick Reference
tmux new -s <name> # New named session
tmux ls # List all sessions
tmux a -t <name> # Attach to session
Ctrl+B, D # Detach from session
tmux kill-session -t <name> # Kill a session
We use tmux extensively for parallel agent development on Fazm. Discussed in r/ClaudeCode.