Claude Code + Git Worktrees: How to Run Parallel AI Agents Without Conflicts

You’re halfway through building a payment feature when a critical auth bug lands in your inbox. With a normal workflow, you stop, stash, switch branches, fix it, then try to remember where you were. With Claude Code and git worktrees, you run both agents simultaneously — and grab coffee while they both finish.

The Problem: One Codebase, One Working Directory

Claude Code is great at focused tasks. But what happens when you want two agents running in parallel — one building a feature, one fixing a bug on a different branch?

They’d step on each other. You can’t git checkout to another branch while an agent is actively editing files. The working directory is shared. There’s no isolation.

The naive solution is to run tasks sequentially. But sequential AI tasks throw away the biggest advantage of agentic coding: you can delegate and walk away. If you’re waiting for one task to finish before starting the next, you’re treating Claude Code like a slower keyboard.

Git worktrees fix this.

What Are Git Worktrees?

A git worktree lets you check out multiple branches of the same repository simultaneously, each in its own directory. They share the same .git history and objects — so you’re not duplicating your entire codebase — but each worktree has its own independent working directory.

Think of it like this:

my-project/                      ← main worktree (main branch)
my-project-fix-auth/             ← worktree 2 (fix/auth-timeout branch)
my-project-feature-payments/     ← worktree 3 (feature/payments branch)

Three directories, one git database. Each agent works in its own space. No conflicts, no file locks, no stepping on each other.

This is a standard git feature — it’s been around since git 2.5. Claude Code builds on top of it.

Method 1: Claude Code’s Built-in Worktree Support

Claude Code has native worktree support. Inside a session, Claude can create a new worktree automatically via the EnterWorktree tool. It creates the worktree under .claude/worktrees/ with a new branch based on HEAD.

The key benefit: Claude handles creation and cleanup. When the session exits, you’re prompted to keep or remove the worktree. No manual pruning.

This is the right choice when you want Claude to manage isolation for you — for example, when running an autopilot task that shouldn’t touch your working branch.

Method 2: Manual Git Worktrees + Multiple Claude Sessions

For more control, create worktrees yourself and open separate Claude Code sessions in each.

Create the worktrees:

# From your main project directory
git worktree add ../my-app-feature-payments -b feature/payments
git worktree add ../my-app-fix-auth -b fix/auth-timeout

Expected output:

Preparing worktree (new branch 'feature/payments')
HEAD is now at a3f2c1d Last commit message

Preparing worktree (new branch 'fix/auth-timeout')
HEAD is now at a3f2c1d Last commit message

List your active worktrees:

git worktree list

/home/user/projects/my-app                      a3f2c1d [main]
/home/user/projects/my-app-feature-payments     a3f2c1d [feature/payments]
/home/user/projects/my-app-fix-auth             a3f2c1d [fix/auth-timeout]

Remove a worktree when done:

git worktree remove ../my-app-feature-payments

# Or prune all stale worktrees at once
git worktree prune

Real Example: Two Features, Zero Waiting

Here’s a concrete workflow. You have a PaymentAPI service. You need to build a new payment processing module and simultaneously fix a session timeout bug.

Open two terminals:

Terminal 1 — Payment feature:

cd ~/projects/payment-api
git worktree add ../payment-api-payments -b feature/stripe-integration
cd ../payment-api-payments
npm install
claude -p "Implement payment processing in src/payments/processor.ts using Stripe. Handle charge, refund, and webhook verification."

Terminal 2 — Auth bug fix:

cd ~/projects/payment-api
git worktree add ../payment-api-auth-fix -b fix/session-timeout
cd ../payment-api-auth-fix
npm install
claude -p "Fix the session timeout bug in src/auth/session.ts. Sessions expire after 5 minutes instead of the configured 30 minutes."

Both agents run simultaneously. Agent 1 doesn’t know Agent 2 exists. Agent 2 doesn’t know Agent 1 exists. They each see a clean copy of the codebase on their own branch.

When both finish, you merge:

# Merge the auth fix first (lower risk)
cd ~/projects/payment-api
git merge fix/session-timeout

# Then merge the payment feature
git merge feature/stripe-integration

What used to be two sequential tasks — 45 minutes each, 90 minutes total — runs in 45 minutes of wall-clock time. You did something else. Both finished.

When to Use Worktrees vs. Single Session

The rule: if two tasks would require two different git checkout operations, they need two worktrees.

Tips and Pitfalls

Don’t check out the same branch in two worktrees. Git will reject this with an error. Each branch can only be checked out in one worktree at a time. Use separate branches.

Each worktree has its own node_modules (or venv, or vendor/). These are not shared. Run npm install (or your equivalent) inside each worktree before starting a Claude session there. Otherwise the agent might fail on missing dependencies.

Clean up worktrees when done. They don’t auto-delete. Run git worktree prune periodically to remove stale ones. Or be explicit with git worktree remove <path>.

Worktrees are cheap. They share git objects, so you’re not copying your entire repo history. The overhead is just the working directory files. This makes them faster to create than a full git clone.

Claude Code’s native worktree support handles cleanup for you. When using the built-in /worktree feature, Claude prompts you on session exit: keep or remove. For manual worktrees, you’re responsible for cleanup.

Don’t run the same Claude session root in two places. Each Claude session should map to one worktree. Sharing a .claude/ directory between worktrees can cause state conflicts.

The Mental Shift

The real value here isn’t just “run two things at once.” It’s a different mental model for how you work with Claude Code.

Without worktrees, you think sequentially: finish task A, start task B. With worktrees, you think in parallel queues: here are three things I need done, start all three, review when ready.

This compounds. If you can run three agents in parallel instead of sequentially, you don’t just save time — you change what’s feasible in a workday. Tasks that felt like “too much for today” become “done by lunch.”

Git worktrees have been in git for years. Most developers know they exist but never use them. Claude Code makes them worth using. When each worktree is being driven by an agent that can work without your supervision, the productivity gain is real.

Set up two worktrees. Open two terminals. Start two Claude sessions. See what finishes first.

Related: Context Window Basics — understanding what Claude sees inside each session.