Claude Code Git Worktrees: Parallel Agents Without Conflicts

Who this is for: developers already running Claude Code on a real repo who want to parallelize — one agent fixing a bug, another building a feature, a third reviewing a PR — without three terminal tabs fighting over the same checked-out branch and the same node_modules.

Claude Code git worktrees solve a problem that shows up the moment you try to run more than one agent session against the same repository: git checkout is global to the working directory, so switching branches in one terminal yanks the files out from under any other process reading them. Worktrees fix this by giving each branch its own directory on disk, sharing a single .git database underneath. Once you wire Claude Code to spin up a worktree per task, you can run three, five, or ten agents in parallel, each on its own branch, each with an isolated filesystem, without a single git stash or merge surprise.

I started doing this seriously in 2026 after burning an afternoon on a merge conflict caused by two Claude Code sessions editing the same branch from two terminal tabs. Worktrees removed the class of bug entirely, not just this one instance of it.

What a git worktree actually is

A worktree is a second (or third, or tenth) working directory attached to the same repository. Instead of git clone-ing the repo again — which duplicates the whole .git history on disk and desyncs the moment you fetch in only one copy — git worktree add checks out a branch into a new folder while all worktrees share one object database.

# from inside your main repo checkout
git worktree add ../myapp-feature-auth feature/auth
git worktree add ../myapp-fix-402 fix/rate-limit-402
git worktree list

That gives you:

/projects/myapp                 <branch: main>
/projects/myapp-feature-auth    <branch: feature/auth>
/projects/myapp-fix-402         <branch: fix/rate-limit-402>

Three real directories, three independent node_modules (if you install separately), three independent running dev servers on different ports, but one shared commit graph. A commit made in one worktree is instantly visible via git log in every other worktree pointed at the same repo.

Why this matters specifically for Claude Code

Claude Code is fast enough that a single agent session can produce a dozen commits an hour. The moment you run two sessions concurrently against one checkout, you get one of three failure modes:

1. Session A checks out a new branch, session B's file reads suddenly return content from the wrong branch mid-task.
2. Both sessions edit the same file on the same branch and one agent's edit silently clobbers the other's.
3. A long-running dev server or test watcher started by session A picks up file changes written by session B and reports failures that have nothing to do with A's actual change.

Worktrees eliminate all three because each agent gets a directory that no other agent touches. You get real OS-level isolation instead of hoping the two conversations stay out of each other's way. This is the same principle behind Claude Code subagents — isolate the blast radius of a unit of work — applied at the git layer instead of the conversation layer.

Setting up a worktree-per-task workflow

The pattern that has worked best for me:

1. Keep a clean main checkout as the source of truth

Never run an agent directly against your primary /projects/myapp checkout if you're also spinning off worktrees from it. Treat that directory as read-mostly — pull, branch, worktree, but don't edit there while other worktrees are active.

2. Name worktree directories after the branch

../myapp-<branch-name> is enough discipline to keep git worktree list scannable once you have six or seven active. I have seen setups fail from nothing more exotic than someone reusing a directory name for two different branches.

3. Launch one Claude Code session per worktree directory

cd ../myapp-feature-auth
claude

Each session's cwd is the worktree root, so every tool call — Read, Edit, Bash — is scoped there automatically. There's no extra Claude Code configuration needed; this is pure git plumbing that Claude Code inherits for free because it operates relative to the working directory.

4. Give each worktree its own dependency install and port

# in each worktree
npm install
PORT=5174 npm run dev   # bump the port per worktree

Skipping the separate npm install is the single most common mistake. Node modules aren't tracked by git, so a fresh worktree has none until you install. If you symlink node_modules between worktrees to save disk space, be aware that a native dependency compiled for one branch's lockfile can silently break another.

5. Clean up worktrees when the branch merges

git worktree remove ../myapp-feature-auth
git branch -d feature/auth

Worktrees left lying around after their branch is merged or deleted will eventually cause git worktree add to fail with "already exists" errors, or worse, keep a stale checkout that someone accidentally edits.

Warning: git worktree remove refuses to run if the worktree has uncommitted changes. That's a feature, not friction — it stops you from silently discarding work an agent left uncommitted.

Letting agents commit and open PRs

Once each agent has its own worktree, the natural next step is letting it commit its own work and open the PR, rather than you doing it by hand after every session. This is where a lot of teams get nervous, and reasonably so — an agent that commits and pushes autonomously needs guardrails, not blind trust.

What I actually run:

• Agent commits locally, never pushes without being asked. Claude Code will create commits mid-task when instructed, but I keep push and PR creation as an explicit final step I approve, especially on shared repos.
• One task, one branch, one PR. Never let a single agent session accumulate unrelated changes across multiple concerns — it makes the diff unreviewable and defeats the entire point of isolating work per worktree.
• Commit messages describe why, not what. The diff already shows what changed; a commit message that just restates the diff is wasted text. This matters more with agent-generated commits because there's no human memory of "I did this because X" to fall back on later.
• PR descriptions include the prompt or task summary. When a reviewer opens a PR six weeks from now, "implement rate limiting on /api/leads" as a PR title with a one-line body is worse than useless. I now require the PR body to state the original task and any deliberate trade-offs the agent made.

# inside a worktree, after Claude Code finishes a task
git add -A
git commit -m "fix: rate limit /api/leads to 10 req/min per IP

Prevents the scraper hitting the endpoint from exhausting
EmailJS quota, seen in prod logs 2026-07-10."
git push -u origin fix/rate-limit-402
gh pr create --fill

Review discipline for agent-authored code

Isolation at the git level doesn't replace review discipline — it makes review discipline actually feasible, because each PR is a clean, single-purpose diff instead of a tangle of three concurrent changes.

Three things I check on every agent-authored PR before merging:

1. Does the diff match the stated task, and only the task? Agents occasionally "helpfully" fix an adjacent lint warning or rename a variable while they're in a file. That's scope creep even when the change itself is correct, and it makes the PR harder to revert cleanly if something else in it breaks.
2. Are there new dependencies, and were they necessary? An agent solving a small problem will sometimes reach for a package instead of ten lines of code. Cheap for the agent, not always cheap for your bundle size or your supply chain.
3. Did tests actually run, or does the PR just claim they did? I ask Claude Code to paste the actual test output into the PR description rather than a summary sentence — a summary can be wrong or aspirational, raw output can't lie about what it printed.

This is the same territory covered in more depth in AI code review tools and in claude-code-permissions-safety if you want to lock down exactly which bash commands an agent is allowed to run unattended.

Avoiding merge conflicts between parallel agents

Worktrees stop agents from clobbering each other's files on disk. They do not stop two branches from touching the same lines and producing a merge conflict when both eventually land on main. Three habits reduce that risk:

• Scope tasks by file ownership when running agents in parallel. If agent A is refactoring src/lib/auth.js and agent B is styling a component that imports it, brief B to avoid touching the import surface, or sequence the two instead of parallelizing them.
• Merge or rebase frequently, not at the end of a long-running branch. A worktree branch that sits unmerged for two weeks while three other branches land on main is the single biggest predictor of a painful conflict resolution session.
• Ask the agent to rebase before opening the PR, not after. git fetch origin && git rebase origin/main inside the worktree, resolved by the agent with your review, is far less disruptive than discovering the conflict during a squash-merge in the GitHub UI.

For nearly everyone running Claude Code day to day, worktrees sit at the sweet spot: real isolation, minutes to set up, no extra infrastructure. If you're going further into autonomous, unattended agents you'll also want to read claude-code-headless-automation for how to run these same worktree-scoped sessions without a human watching the terminal.

A minimal multi-agent worktree script

If you find yourself doing this by hand more than twice a week, script it:

#!/usr/bin/env bash
# new-worktree.sh <branch-name>
set -e
BRANCH="$1"
DIR="../$(basename "$PWD")-${BRANCH//\//-}"

git fetch origin
git worktree add "$DIR" -b "$BRANCH" origin/main
cd "$DIR"
npm install
echo "Worktree ready at $DIR on branch $BRANCH"

Run it, cd into the directory it prints, and launch claude there. Ten seconds of typing instead of five manual commands, and it's consistent enough that you won't end up with mismatched branch/directory names six months in.

FAQ

Do git worktrees work with any git hosting provider?

Yes. Worktrees are a local git feature, not something GitHub, GitLab, or Bitbucket need to support. Pushing, pulling, and opening PRs from a worktree branch behaves identically to doing so from a normal checkout, because remotely there's no such thing as a worktree — only branches and commits.

Can two worktrees be on the same branch at the same time?

No. Git refuses to check out the same branch into two worktrees simultaneously, because that would recreate exactly the race condition worktrees exist to prevent. If you need two agents genuinely working on the same feature, give them two branches and merge, or have one agent own the branch while the other reviews.

How much disk space do worktrees actually cost?

Only the size of one working tree per worktree, since the .git object database is shared. The real cost is usually node_modules, not git objects — ten worktrees of a typical React app can easily mean ten multi-hundred-megabyte node_modules directories, so prune worktrees you're done with.

Does Claude Code need special configuration to use worktrees?

No. Claude Code operates relative to its working directory, so launching a session inside a worktree directory is functionally identical to launching it inside any other checkout. There is no worktree-specific setting; the isolation comes entirely from git and your filesystem layout.

What happens if I delete a worktree directory manually instead of using git worktree remove?

Git's internal bookkeeping in .git/worktrees/ will still reference the deleted path, and future git worktree list or git worktree add calls may error out referencing a directory that no longer exists. Run git worktree prune afterward to clean up the stale metadata.

Get help wiring this into your team

If you want a Claude Code + git worktree setup tailored to your actual repo and branching strategy, I offer a free 30-minute call to walk through it. Reach out via the contact form or message me directly on wa.me/972585802298.

Sources

• Git worktree documentation
• GitHub CLI documentation
• Claude Code documentation
• Anthropic Claude Code overview