Running 10+ Claude Code Agents Without Chaos - Tmux Orchestration

Fazm Team··2 min read

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-frontend
  • tmux new-session -d -s agent-backend
  • tmux 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:

  1. Spawn agents with specific tasks and worktrees
  2. Monitor each session for completion or errors
  3. Collect results and merge branches
  4. 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.

More on This Topic

Related Posts