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

TL;DR — Git worktrees let you check out multiple branches of the same repo simultaneously, each in its own directory. Combined with Claude Code, you can run parallel AI agents on different tasks with zero conflicts — turning two sequential 45-minute tasks into 45 minutes of wall-clock time. Jump to the parallel workflow →

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.

What Is the Problem with 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.

Key insight: Running Claude Code agents sequentially discards their primary advantage: unattended execution. When each worktree isolates a branch in its own directory, two agents can work simultaneously without file locks or checkout conflicts — converting two 45-minute sequential tasks into 45 minutes of wall-clock time while the developer does something else entirely.

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.

Key insight: Git worktrees have been available since git 2.5, allowing multiple branches of a single repository to be checked out simultaneously in separate directories. They share the same .git object database — no duplication of history — while each directory maintains an independent working tree, index, and HEAD pointer.

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

How Do You Run Two Features in Parallel with 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) now runs in 45 minutes of wall-clock time. You did something else. Both finished.

Key insight: The parallel worktree workflow requires three setup steps per branch: git worktree add to create the isolated directory, dependency installation (npm install or equivalent) inside the worktree, and a separate Claude Code session started from that directory. Each agent sees a clean copy of the codebase on its own branch with no awareness of the other agent’s work.

When Should You Use Git Worktrees vs. a Single Session?

Scenario	Approach
One focused task	Single session, no worktree needed
Two unrelated tasks on different branches	Git worktrees: run parallel
Quick context switch (check something, come back)	`/clear` or just ask: no worktree needed
CI/CD running Claude on multiple PRs	Worktrees per PR: mandatory
Large refactor + hotfix simultaneously	Worktrees: keep refactor isolated
Testing a risky change before committing	Worktree as a sandbox

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

What Are the Key Tips and Pitfalls with Git Worktrees?

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.

Key insight: Git worktrees are cheap to create because they share the repository’s object database — no duplication of commit history or blobs. The overhead is only the working directory files themselves. This makes worktree creation faster than git clone while providing the same branch isolation that prevents Claude Code agents from interfering with each other.

What Mental Shift Does Parallel AI Development Require?

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.”

Key insight: The mental model shift from sequential to parallel AI development changes what’s feasible in a workday, not just how fast individual tasks complete. Running three agents simultaneously instead of sequentially doesn’t just save time — it makes previously infeasible work possible by eliminating the waiting cost that made complex multi-task days feel unmanageable.

Try it now: Pick two tasks you have queued for today. Run git worktree add ../your-project-task2 -b task/your-branch-name and open a second terminal. Start both Claude sessions simultaneously. Come back in 30 minutes and review both results.

Get weekly Claude Code tips — One practical tip every week. No fluff, no spam. Subscribe to AI Developer Weekly →

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.