Managing Parallel AI Agents with tmux and Git Worktrees

Running five AI agents on the same codebase sounds great until they start overwriting each other's changes. The solution uses two tools that have been around for years: tmux for visibility and git worktrees for isolation. Neither was designed for AI agents, but the combination works extremely well.

Why Branches Alone Are Not Enough

If two agents share the same working directory on different branches, every git checkout clobbers uncommitted changes. Agent 1 checks out its branch, makes changes, agent 2 checks out its branch - agent 1's uncommitted work is gone. Even if you commit frequently, the working directory is shared, which means file locks and build artifacts collide.

Git worktrees solve this by giving each branch its own physical directory on disk. They all point to the same .git directory - same history, same remotes, same commits - but each has an independent working tree. Agent 1 can run a build in its directory at the same time agent 2 runs tests in its own directory. No conflicts, no clobbering.

Setting Up Worktrees

# From your main repository directory
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

# Verify worktrees are set up
git worktree list
# Output:
# /Users/you/project          abc1234 [main]
# /Users/you/project-agent-1  abc1234 [feature/agent-1]
# /Users/you/project-agent-2  abc1234 [feature/agent-2]
# /Users/you/project-agent-3  abc1234 [feature/agent-3]

Each worktree starts from the same commit as your main branch. The branch is created automatically. Now each agent has a completely isolated working environment.

tmux Layout for Parallel Monitoring

# Create a new tmux session for agent work
tmux new-session -s agents -d

# Create panes for each agent
tmux split-window -h -t agents        # Split horizontally
tmux select-pane -t agents:0.0
tmux split-window -v -t agents:0.0    # Split first column vertically
tmux select-pane -t agents:0.2
tmux split-window -v -t agents:0.2    # Split second column vertically

# Navigate each pane to its worktree
tmux send-keys -t agents:0.0 "cd ../project-agent-1" Enter
tmux send-keys -t agents:0.1 "cd ../project" Enter          # Your coordination pane
tmux send-keys -t agents:0.2 "cd ../project-agent-2" Enter
tmux send-keys -t agents:0.3 "cd ../project-agent-3" Enter

# Attach to the session
tmux attach -t agents

The result is a 2x2 grid: three agent panes and one pane you control for git operations, reviews, and coordination.

Starting Agents in Each Pane

# In pane 0 (agent 1 - frontend work)
claude "Implement the login form component in src/components/Login.tsx.
Use the types in src/types/auth.ts. Do not modify any files outside src/components/."

# In pane 2 (agent 2 - backend work)
claude "Add the /api/auth/login endpoint in src/api/auth.ts.
Follow the interface defined in src/types/auth.ts. Do not modify frontend files."

# In pane 3 (agent 3 - tests)
claude "Write tests for the authentication flow in src/__tests__/auth.test.ts.
Read the types in src/types/auth.ts to understand the interface."

The shared src/types/auth.ts file is the contract between agents. Each agent reads from it but only one agent should own it. Define interfaces before starting agents.

Tools That Automate This Setup

Several community tools have emerged to automate the worktree + tmux setup:

workmux (github.com/raine/workmux) - ties worktrees with tmux windows and streamlines the merge flow. TUI dashboard showing all active agents across tmux sessions.

muxtree (github.com/b-d055/muxtree) - single bash script, three setup questions, gives you a branch, worktree, and tmux session with two windows (code viewer + agent) per task.

dmux (github.com/standardagents/dmux) - press n, type a prompt, pick an agent, handles worktree creation and agent launch automatically.

For regular use, the manual setup above is worth understanding before adopting a wrapper. Knowing what the wrappers do prevents confusion when they fail.

Monitoring Across Panes

The key tmux bindings for multi-agent monitoring:

• prefix + z - zoom into a pane for detailed review, press again to return to split view
• prefix + [ - scroll through a pane's history without interrupting the agent
• prefix + q - flash pane numbers for quick navigation
• prefix + { / prefix + } - swap panes

The zoom-in / zoom-out cycle (prefix + z) becomes the core interaction pattern. See something interesting in an agent's output, zoom in to read it carefully, zoom back out to monitor all agents.

Merge Strategy After Parallel Work

When agents finish, you have independent branches with potentially overlapping changes. Three situations:

Feature slices (agents worked on different parts of the system): merge sequentially, resolve any conflicts manually.

cd ../project           # Your main repo
git merge feature/agent-1 --no-ff -m "Merge frontend agent work"
git merge feature/agent-2 --no-ff -m "Merge backend agent work"
git merge feature/agent-3 --no-ff -m "Merge test agent work"

Competing approaches (agents worked on the same problem): compare branches, pick the best implementation, cherry-pick specific commits if needed.

git diff feature/agent-1..feature/agent-2  # Compare approaches
git checkout feature/agent-1               # Pick the winner
git cherry-pick <commit-hash-from-agent-2> # Take specific improvements

Review and merge selectively: use git log feature/agent-1 --oneline to see what each agent did, then cherry-pick only the commits you want.

Cleanup After Sessions

# Remove a worktree when done
git worktree remove ../project-agent-1
git branch -d feature/agent-1

# Or remove all agent worktrees at once (careful)
for i in 1 2 3; do
  git worktree remove ../project-agent-$i 2>/dev/null
  git branch -d feature/agent-$i 2>/dev/null
done

Cleaning up worktrees after sessions prevents stale directories from accumulating. The .git/worktrees/ directory holds metadata for each - git worktree prune cleans up stale entries if directories were removed manually.

The worktree + tmux combination turns parallel agent management from chaos into a structured workflow with real isolation guarantees.

More on This Topic

• Terminal IDE with Multiple AI Agents
• Tmux and Terminal Review Tools for Parallel Agents
• Managing Parallel Claude Agents

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