Git Worktrees: Run AI Coding Agents in Parallel (2026)

Table of Contents

Stop Queuing Your Agents Up One at a Time

You open Claude Code, hand it a task, and then you wait. Three minutes later it asks for a decision, you answer, and you wait again. Meanwhile your second task — the one you could have started in parallel — is just sitting in your head, and your third one hasn’t even been written down yet.

Git worktrees fix that. A worktree is a second (or third, or fifth) working directory attached to the same Git repository. Each one checks out its own branch, with its own files, its own index, and its own HEAD — while all of them share the same underlying repo database. That means you can point a separate AI coding agent at each worktree and run them all at once, without them stepping on each other’s files.

This guide shows you the full loop: creating worktrees, bootstrapping each one so agents actually run cleanly, launching parallel agents with prompts that keep them in their lane, merging the results back, and cleaning up. Everything here was verified against the official Git documentation and current 2026 practitioner guides on October 12, 2026.

What Git Worktrees Actually Are

A normal git clone gives you one repository and one working tree — the “main worktree.” Linked worktrees are additional working trees attached to that same repository. The Git docs put it simply: a repository has one main worktree and zero or more linked worktrees, and a worktree is just “the working tree, along with this metadata” that distinguishes it from the others.

The sharing rules matter more than the definition. All worktrees share the commit database: objects, branches, tags, remotes, and refs. If an agent commits something in one worktree, every other worktree sees that commit immediately — no git fetch needed. What stays private to each worktree:

The working files on disk — each worktree has its own copy of the project files.
The index (staging area) — staging in one worktree doesn’t touch the others.
The HEAD — each worktree points at its own branch.

Think of it as parallel universes of your code that all share the same history. One rule is enforced hard: the same branch cannot be checked out in two worktrees at the same time. Try it and git worktree add refuses (unless you force it, which you shouldn’t). That one guardrail is what keeps parallel agents from overwriting each other’s work.

Why Parallel Agents Break Without Worktrees

Run two AI agents in the same working directory and you’ll discover the failure modes fast:

Index fights. Agent A stages and commits files while Agent B is mid-edit. Branches get switched, stashes pile up, and somebody’s uncommitted work lands in the wrong commit.
Dependency churn. Agent A runs npm install some-package while Agent B’s file watchers go wild and its dev server restarts with an unexpected dependency graph.
Silent context pollution. Agent A modifies a shared file “temporarily” for its task. Agent B reads that file, assumes the modification is the real state of the world, and builds on top of a lie.

Humans hit the same wall, which is why worktrees have existed since Git 2.5 — but AI agents make the pain sharper, because they work faster and check less. Isolation at the filesystem level is the only fix that actually holds.

Set Up Your First Worktree in Five Minutes

From the root of your repository:

# Create a worktree for the auth feature on a new branch
git worktree add -b feature/auth ../myapp-auth

# One for the dashboard feature
git worktree add -b feature/dashboard ../myapp-dashboard

# See what you've got
git worktree list

That’s it. Each command creates a new directory at the given path, creates (or checks out) the branch, and points the new worktree at it. A couple of conveniences from the official docs worth knowing:

If you skip -b, Git names the branch after the last component of the path — git worktree add ../hotfix creates and checks out a branch called hotfix.
To work on an existing branch in a new worktree, pass the branch as the commit-ish: git worktree add ../myapp-auth feature/auth.
For throwaway experiments, git worktree add -d ../scratch creates a worktree with a detached HEAD — no branch attached, easy to discard.

Commit your current work first. A new worktree checks out the branch at its current state — uncommitted and untracked files in your main worktree are not copied over. If the task depends on work-in-progress, commit it (even to a temp branch) before spinning up the worktree.

Bootstrap Each Worktree Like a Fresh Machine

This is the step most guides skip, and it’s the difference between agents that run cleanly and agents that mysteriously fail. Treat every new worktree as a fresh checkout on a fresh machine:

cd ../myapp-auth

# Dependencies: install fresh in EVERY worktree.
# Do NOT symlink node_modules from the main worktree —
# sharing the dependency tree reintroduces the race conditions
# you just eliminated.
npm install

# Copy environment files (untracked files are NOT copied to new worktrees)
cp ../myapp/.env .env

# If your dev server needs a port, give each worktree its own
PORT=3001 npm run dev

Dependencies per worktree. Separate node_modules per agent is non-negotiable. Disk space is cheap; dependency race conditions are expensive.
Env and secrets per worktree. Because untracked files don’t carry over, copy .env files and any local config explicitly.
Ports per worktree. If agents start dev servers, databases, or watchers, assign a distinct port (3001, 3002, 3003) so they don’t collide.
Keep worktrees out of version control. If you prefer worktrees inside the repo folder instead of alongside it, put them in a subdirectory like .trees/ and add it to .gitignore — one line: echo '.trees/' >> .gitignore. Some teams standardize on this layout so every developer’s worktrees live in the same place.

Launch Your Agents With Scoped Prompts

With the worktrees ready, open a terminal per worktree and start your agent — claude, codex, whatever you use. Each instance gets its own directory, its own branch, and its own dependencies. They genuinely cannot step on each other.

The prompt matters as much as the setup. Vague prompts produce agents that wander across the whole codebase; scoped prompts produce agents that stay in their lane:

Task: Add rate limiting to the auth API.
Scope: only files under src/routes/auth/ and src/middleware/.
You must NOT touch src/routes/billing/ or anything under src/db/migrations/.
Success criteria: 429 responses after 100 requests/minute per IP,
plus tests in tests/auth/rate-limit.test.ts. All tests must pass.

Three habits that make parallel runs work:

Map file boundaries first. Decide which files each agent owns before launching anything. Overlap is where merge pain comes from.
Branch from the same clean base. Create all worktrees from the same main commit so the agents start from identical context.
Remember the cost. Three agents running at once is three times the API spend. Parallelism buys wall-clock time, not money — keep task scopes tight so the spend is worth it. (If you’re deciding which model to burn tokens on in each agent, our 2026 benchmark breakdown is a good starting point.)

Merge the Results Back Without Tears

When the agents finish, you hold several finished branches and one main. Merge them one at a time, running the test suite between each merge. That single discipline catches 90% of integration problems while they’re still small:

# From your main worktree
git checkout main

# Merge sequentially, testing between each one
git merge feature/auth
npm test

git merge feature/dashboard
npm test

# Push when everything is green
git push origin main

Notes from the trenches:

Since all worktrees share the same repo database, your main worktree sees the agent branches the moment they’re committed — no fetching, no pulling.
If two agents touched nearby code, the second merge may conflict. That’s normal Git, not a worktree problem — resolve it in the main worktree.
Before merging an agent’s branch, ask an agent (or a fresh session) to review the diff with adversarial intent. Our AI code review prompts guide has patterns built for exactly this.

Clean Up When You’re Done

Removing a worktree is one command, and Git is conservative about it:

# From anywhere in the repo (not inside the worktree you're removing)
git worktree remove ../myapp-auth

# The worktree had uncommitted changes? --force overrides the safety check
git worktree remove --force ../myapp-dashboard

# Then delete the branch if you're done with it
git branch -d feature/auth

# Clean up stale metadata from worktrees deleted without `remove`
git worktree prune

git worktree remove refuses to delete a worktree with uncommitted changes unless you pass --force — that’s a feature, not a bug.
You cannot remove the main worktree.
If you deleted a worktree directory manually (with rm -rf), run git worktree prune to clear its leftover administrative files. git worktree prune -n dry-runs it first.
If a worktree lives on a drive that’s not always mounted, git worktree lock stops Git from pruning it automatically.
Moved a worktree folder manually? git worktree move does it properly; if you already moved it by hand, git worktree repair reconnects it.

The Gotchas Nobody Tells You

Branch exclusivity bites in scripts. Automation that creates worktrees needs unique branch names per run — a second add on the same branch name refuses. Suffix branch names with the agent or run name.
Disk usage multiplies. Every worktree is a full checkout plus its own node_modules. Three worktrees of a big monorepo can eat tens of gigabytes. Worth it, but know the cost.
Hooks and Git config are shared. All worktrees share the repo’s hooks and local config. A pre-commit hook runs in every worktree — usually what you want, occasionally surprising.
Agents can see each other’s branches. The shared database means an agent in worktree A can git log worktree B’s branch. That’s a feature for review, but don’t assume isolation you haven’t scoped in the prompt.
Stateful services still collide. Worktrees isolate files, not databases. If two agents need Postgres, give them separate databases or containers — the worktree won’t do that for you.

When Worktrees Are the Wrong Tool

Worktrees are for parallel, independent, file-scoped work. Skip them when:

Two agents genuinely need to edit the same files — you’ll just manufacture merge conflicts.
The task is a 10-minute fix. The bootstrap cost (install, env, ports) outweighs the benefit.
Your bottleneck is thinking, not waiting — if you’re actively reviewing every agent output in real time, one agent is already enough.

How to Run Multiple AI Coding Agents in Parallel with Git Worktrees (2026)