Back to Blog

How to Manage Multiple Claude Code Sessions with tmux

Fazm Team··2 min read
claude-codetmuxdeveloper-toolsproductivityworkflow

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:

  1. Create a branch for each agent's task: git checkout -b feat/refactor-capture-pipeline
  2. Start the Claude Code session in that branch
  3. 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.

Related Posts