Git Worktrees: Enabling Parallel Agent Execution

“One repo, many agents, zero conflicts.”

The Collision Problem

Imagine you have three AI agents and you want them all to work on different bugs at the same time:

Agent A: Fix bug #123
Agent B: Fix bug #124
Agent C: Fix bug #125

This sounds straightforward until you think about how git works. All three agents need to create their own branches, make changes to files, and then commit and push their work. With standard git workflows, this creates chaos. Agent A starts working on a branch, Agent B tries to check out a different branch but can’t because there are uncommitted changes. Agent C creates a commit that accidentally includes changes Agent A was working on. Branches collide, merge conflicts multiply, and what should have been three simple fixes becomes a coordination nightmare.

This is the parallelism problem for AI agents. We want them to work simultaneously—that’s the whole point of having multiple agents. But standard git assumes one person working on one thing at a time.

Git Worktrees: The Solution

Git has a feature called worktrees that most developers never discover. A worktree lets you check out multiple branches of the same repository simultaneously, each in its own directory. Instead of having one copy of your repo that switches between branches, you can have multiple copies, each on a different branch, all sharing the same underlying git history.

The directory structure looks like this:

repo/                    # Main worktree (main branch)
.worktrees/
├── issue-123/          # Worktree for bug #123
├── issue-124/          # Worktree for bug #124
└── issue-125/          # Worktree for bug #125

Each agent gets its own directory with its own branch. Complete isolation. No conflicts. Agent A can commit changes in issue-123 while Agent B is in the middle of editing files in issue-124, and neither affects the other.

How Worktrees Work

The basic command to create a worktree looks like this:

git worktree add ../.worktrees/issue-123 -b solve/issue-123 origin/main

This single command does three things. First, it creates a new directory at ../.worktrees/issue-123. Second, it creates a new branch called solve/issue-123 based on the latest code from origin/main. Third, it checks out that new branch in the new directory, so you have a complete working copy ready to go.

Once the worktree exists, an agent can work in complete isolation:

cd ../.worktrees/issue-123
# Make changes, commit, push
git add .
git commit -m "Fix issue #123"
git push -u origin solve/issue-123

Everything works exactly like a normal git workflow, except changes happen in an isolated directory on an isolated branch. The agent can create a pull request directly from the worktree:

gh pr create --title "Fix #123" --body "..."

When the work is done, cleanup is simple. Return to the original repository and remove the worktree:

cd /original/repo
git worktree remove ../.worktrees/issue-123 --force

The directory disappears, but the branch and any commits remain. If the PR gets merged, you can delete the branch too. If the work needs to continue, just create a new worktree from that branch.

Our Pattern for Parallel Issue Solving

We’ve codified this into a script that handles the full workflow:

#!/bin/bash
# solve-issue.sh

ISSUE=$1
WORKTREE="../.worktrees/issue-$ISSUE"
BRANCH="solve/issue-$ISSUE"

# Create isolated worktree
git worktree add "$WORKTREE" -b "$BRANCH" origin/main

# Work happens here (agent executes)
cd "$WORKTREE"

# ... agent makes changes ...

# Commit and push
git add .
git commit -m "Fix #$ISSUE"
git push -u origin "$BRANCH"

# Create PR
gh pr create --title "Fix #$ISSUE" --body "..."

# Clean up
cd -
git worktree remove "$WORKTREE" --force

The script handles creation, execution, and cleanup as a single unit. The agent never touches the main repository—it does all its work in an isolated directory, produces a pull request, and cleans up after itself.

True Parallelism in Action

With worktrees, running agents in parallel becomes trivial:

# Launch 3 agents in parallel
solve-issue 123 &
solve-issue 124 &
solve-issue 125 &
wait

Each agent runs in its own process with its own worktree. They can all make commits at the same time without interfering with each other. When they finish, you have three separate pull requests ready for review, each with a clean commit history showing exactly what that agent changed.

This pattern transforms how you think about agent-assisted development. Instead of queuing up work and processing it sequentially, you can throw problems at multiple agents simultaneously and collect the results.

Why This Works So Well

The benefits of worktrees extend beyond just avoiding conflicts.

First, there’s complete branch isolation. Each worktree has its own branch, and it’s literally impossible for one agent to accidentally modify another agent’s work. The isolation is enforced at the filesystem level.

Second, every worktree starts from a known clean state. When you create a worktree from origin/main, you get exactly what’s on main—no leftover changes from previous work, no accidentally included files. This reproducibility makes debugging much easier.

Third, cleanup is trivial. Remove the worktree directory and it’s gone. If a task fails or needs to be abandoned, you don’t have half-finished work polluting your main repository. The branch can be deleted if needed, or kept for later continuation.

Fourth, you get a natural audit trail. Each agent’s work lives in a separate branch, which becomes a separate pull request, which goes through a separate review. You can see exactly what each agent did without untangling interleaved commits.

Things That Can Go Wrong

Worktrees are powerful but have some limitations worth knowing.

Git imposes a limit on concurrent worktrees—usually around ten. This isn’t a hard limit, but if you try to create too many worktrees simultaneously, you might hit issues. The solution is simple: clean up worktrees when you’re done with them rather than letting them accumulate.

Worktrees share git objects with the main repository. This is actually an efficiency feature—it means worktrees don’t duplicate all the git history—but it has a consequence. If you delete the main repository, all the worktrees break because they depend on it for the underlying git data.

You can’t have two worktrees on the same branch. Each worktree needs a unique branch. This makes sense when you think about it—if two worktrees were on the same branch, commits from one would show up in the other, defeating the purpose of isolation.

If your repository uses submodules, you’ll need to initialize them separately in each worktree. After creating a worktree, run git submodule update --init to set up the submodules in that isolated directory.

When Worktrees Make Sense

Worktrees add complexity—you’re managing multiple directories instead of one. That overhead is worth it in specific situations.

Use worktrees when you need genuine parallel execution. If you’re running multiple agents on different tasks and they all need to make commits, worktrees eliminate the coordination problem entirely.

Use worktrees for long-running tasks that shouldn’t block other work. If an agent might work for hours on a complex fix, you don’t want that work locking up the main repository for the duration.

Use worktrees for experimental work you might abandon. Creating a worktree is cheap, and deleting one that didn’t pan out is just as easy. You can explore approaches in parallel and keep only what works.

Don’t bother with worktrees for simple sequential tasks. If you’re running one agent at a time, standard git workflows work fine. Don’t add complexity when you don’t need it. Similarly, for quick one-off changes, just work directly in the main repository—worktrees aren’t worth the setup overhead for a five-minute fix.

Integration with Claude Code

We’ve integrated worktrees into our /solve-issue command in Claude Code. When you run the command, it automatically creates an isolated worktree, executes the fix in that worktree, commits the changes, pushes to a branch, creates a pull request, and cleans up the worktree afterward. The main repository stays completely untouched throughout the process.

This means you can point Claude Code at multiple issues and let it solve them in parallel. Each solution gets its own clean branch and PR. You review and merge them independently. The agents never step on each other’s work, and you never have to untangle confused git state.

Managing Your Worktrees

A few commands help you keep track of what’s happening:

To see all active worktrees:

git worktree list

To check if any worktrees have been orphaned (their directories deleted without proper cleanup):

git worktree prune --dry-run

To clean up orphaned worktrees:

git worktree prune

Regular cleanup keeps your repository healthy and avoids the accumulation of stale worktree references.

Try parallel issue solving with worktrees:

git worktree list

Or get started with Claude Code.

---

This is part of the Engineering AI Agents series—practical patterns for building autonomous AI systems.