Running 10+ Claude Code Agents Without Chaos - Tmux Orchestration
Running 10+ Claude Code Agents Without Chaos
Running a single Claude Code agent is straightforward. Running ten in parallel on the same codebase is where things get interesting. The orchestrator pattern using tmux is the most practical approach people have found - each agent gets its own session, its own context, and its own slice of work.
The Tmux Pattern
The setup is simple. Each agent runs in a dedicated tmux session with a descriptive name:
tmux new-session -d -s agent-frontendtmux new-session -d -s agent-backendtmux new-session -d -s agent-tests
You can monitor all of them from a single terminal, switch between sessions to check progress, and kill any agent that goes off the rails without affecting the others.
Isolation Is Everything
The biggest challenge with parallel agents is not running them - it is keeping them from stepping on each other. Each agent needs a clear, non-overlapping scope. "Refactor the auth module" and "update the auth tests" will create merge conflicts. "Build the new settings page" and "add API rate limiting" will not.
Git worktrees help here. Each agent works on its own worktree, so file system conflicts are impossible. When the work is done, you merge each branch independently.
The Orchestrator Layer
A lightweight orchestrator script can manage the whole fleet:
- Spawn agents with specific tasks and worktrees
- Monitor each session for completion or errors
- Collect results and merge branches
- Report what got done and what failed
Some people build this as a simple bash script. Others use a Swift or Python wrapper that watches tmux session output. The key is keeping the orchestrator dumb - it just manages sessions and tasks, not the actual coding logic.
Practical Limits
Ten agents is roughly the sweet spot on a modern Mac. Beyond that, you start hitting API rate limits more than hardware limits. The real constraint is task decomposition - finding ten genuinely independent pieces of work is harder than it sounds.
Fazm is an open source macOS AI agent. Open source on GitHub.