Managing Parallel AI Agents with tmux and Git Worktrees

Running five AI agents on the same codebase sounds great until they start stepping on each other's changes. The solution is surprisingly old-school: tmux for visibility and git worktrees for isolation.

The Setup

Each agent gets its own tmux pane and its own git worktree. A worktree is a separate checkout of the same repository - same git history, different working directory, different branch. This means each agent can edit files, run builds, and make commits without affecting any other agent.

The tmux layout gives you a bird's-eye view of all agents at once. You can see which ones are working, which ones are stuck, and which ones are done.

# Create worktrees for each agent
git worktree add ../project-agent-1 -b feature/agent-1
git worktree add ../project-agent-2 -b feature/agent-2
git worktree add ../project-agent-3 -b feature/agent-3

Why Not Just Branches?

Branches alone are not enough. If two agents are on different branches but sharing the same working directory, every git checkout clobbers the other agent's uncommitted changes. Worktrees solve this by giving each branch its own physical directory on disk.

This also means each agent can run its own build process, its own test suite, and its own dev server without port conflicts or file locks.

The tmux Workflow

A typical session looks like this:

1. Open a tmux session with one pane per agent
2. Each pane is cd'd into its own worktree
3. Start a Claude Code session in each pane with a specific task
4. Monitor progress across all panes simultaneously
5. When agents finish, review their branches and merge the best work

The key insight is that tmux is not just for viewing - it is for orchestration. You can send commands to specific panes, resize them to focus on a struggling agent, or kill a runaway session without affecting the others.

Merge Strategy

When all agents finish, you have multiple branches with independent implementations. The merge strategy depends on the task:

• Feature slices: Each agent worked on a different part, so merge all branches sequentially
• Competing approaches: Agents worked on the same problem, so compare and pick the best one
• Review and cherry-pick: Take the best pieces from each branch

This approach turns parallel agent management from chaos into a structured workflow.

More on This Topic

• Git Worktree Isolation for Multi-Agent Development
• Managing Parallel Claude Agents
• Terminal IDE with Multiple AI Agents

Fazm is an open source macOS AI agent. Open source on GitHub.