AI April 10, 2026

Claude Code Worktrees: Run Parallel AI Coding Sessions (Zero Conflicts)

Learn how to use the claude --worktree flag to run multiple AI coding tasks at the same time. Master isolated branches, .worktreeinclude, and parallel development.

You’re halfway through building a feature. Claude Code is editing files, tests are passing, things are flowing. Then your teammate pings you — “Hey, can you quickly fix that login bug? It’s blocking production.”

Now you’re stuck. You can’t just switch branches — Claude is in the middle of something. Stashing changes is messy. Opening a second terminal on the same repo? That’s asking for merge conflicts.

This is exactly the problem claude --worktree solves.

Understanding Git Worktrees for AI Coding

Before we talk about Claude, let’s understand the git concept behind it.

Think of it like this — you have one notebook (your git repo). Normally, you can only have one page open at a time (one branch checked out). If you want to work on a different page, you have to bookmark the current one, close it, and flip to the new page.

A worktree gives you a second desk with the same notebook open to a different page. Both desks share the same notebook, but you can read and write on different pages simultaneously. No bookmarking. No flipping back and forth.

In git terms:

git worktree add ../bugfix-login bugfix/login

This creates a new directory (../bugfix-login) with the bugfix/login branch checked out. Your main directory stays untouched. Two branches, two directories, zero conflicts.

Enter claude --worktree

Claude Code wraps this git feature into a single flag. Instead of manually creating worktrees, managing branches, and navigating directories — you just run:

claude --worktree feature-auth

That’s it. Here’s what happens behind the scenes:

  1. Claude creates a git worktree at .claude/worktrees/feature-auth
  2. A new branch worktree-feature-auth is created from origin/HEAD
  3. Claude starts a session inside that isolated directory
  4. Your main working directory stays completely untouched

The short flag works too:

claude -w feature-auth

You can even skip the name and let Claude generate one for you:

claude -w

Real-World Example — Two Tasks, Zero Conflicts

Let’s walk through a realistic scenario. You’re working on an e-commerce app. You need to:

  1. Add a wishlist feature — new API endpoint, database model, frontend component
  2. Fix a checkout bug — users are getting charged twice on slow connections

Both tasks are urgent. Both touch different parts of the codebase. Normally, you’d do them one after the other. With worktrees, you do them side by side.

Terminal 1 — Start the feature work

claude -w wishlist "Add a wishlist feature. Users should be able to 
add products to their wishlist, view it, and remove items. 
Create the API endpoints, database migration, and React components."

Claude spins up an isolated worktree and starts building. Your main branch? Untouched.

Terminal 2 — Fix the bug

Open a second terminal in the same repo directory:

claude -w bugfix-double-charge "Fix the double charge bug in checkout. 
The issue is that when the network is slow, users can click the 
pay button multiple times. Add idempotency to the payment endpoint."

Now you have two Claude sessions running in parallel. Each one has its own branch, its own files, its own changes. They can’t step on each other.

Here’s what your directory structure looks like:

your-project/
├── .claude/
│   └── worktrees/
│       ├── wishlist/           # Branch: worktree-wishlist
│       └── bugfix-double-charge/  # Branch: worktree-bugfix-double-charge
├── src/                        # Your main branch — untouched
├── package.json
└── ...

When each session finishes, Claude asks you what to do. If you’re happy with the changes, keep the worktree. Then create a PR from each branch. Two tasks done in the time it would’ve taken to do one.

Combine It with Other Flags

The real power comes when you combine --worktree with other flags.

Fire and forget with --print

Don’t need an interactive session? Use --print mode:

claude -w lint-fix -p "Fix all ESLint errors in the src/ directory"

This runs non-interactively. Claude does the work and exits. Perfect for quick cleanup tasks you don’t want to babysit.

Headless mode for background tasks

Combine with --dangerously-skip-permissions for fully automated tasks (only in trusted environments):

claude -w test-refactor \
  --dangerously-skip-permissions \
  -p "Refactor all test files to use vitest instead of jest"

This runs without asking for permission on file edits. Use this carefully — it’s like giving someone your house keys. Only do it when you trust what’s being done.

Cleaning Up Claude Code Worktrees (when you’re done)

When a worktree session ends, Claude handles cleanup smartly:

If no changes were made — the worktree and branch are deleted automatically. Clean exit, no mess.

If there are changes — Claude asks you:

  • Keep — the worktree stays. You can come back to it later.
  • Remove — everything gets deleted, including uncommitted changes.

To resume a kept worktree later:

cd .claude/worktrees/wishlist
claude --continue

The .worktreeinclude File

Here’s a gotcha that trips people up. Worktrees are fresh checkouts. Your .env file? Not there. Your config/local.json? Gone. Any gitignored file that your app needs to run won’t exist in the worktree.

The fix is simple. Create a .worktreeinclude file at your repo root:

# Don't forget your local environment variables
.env
.env.local
config/secrets.json

This tells Claude to copy these gitignored files into new worktrees. It uses .gitignore syntax, so patterns work too:

.env*
config/*.local.json

Things to Keep in Mind

A few gotchas before you go all-in:

Dependencies need installing. Each worktree is a fresh checkout. If your project uses node_modules, you’ll need to run npm install (or pnpm install) in the worktree. Claude usually handles this, but keep it in mind.

Same branch can’t be checked out twice. Git doesn’t allow the same branch in two worktrees. Each worktree gets its own branch — that’s by design.

Base branch comes from origin/HEAD. If your repo’s default branch changed recently, your local git might still point to the old one. Sync it with:

git remote set-head origin -a

Add worktrees to .gitignore. You probably don’t want worktree directories showing up as untracked files:

.claude/worktrees/

When Should You Use This?

Not every task needs a worktree. Here’s a quick mental model:

Use --worktree when:

  • You want to run multiple Claude sessions at once
  • You’re in the middle of something and need to context-switch
  • The task is big enough that you don’t want it polluting your main branch
  • You want to compare two different approaches in isolation

Skip it when:

  • It’s a quick one-file change
  • You’re not doing anything else in the repo
  • You’re already in a clean state with nothing to protect

Think of it like opening a new browser tab vs a new browser window. Sometimes a tab is enough. But when you need real isolation, open that new window.

Wrapping Up

claude --worktree takes the pain out of parallel development with AI. No manual branch management. No stashing. No conflicts. Just spin up isolated sessions and let them run.

The workflow is dead simple:

claude -w feature-name "your prompt here"

Two terminals. Two tasks. Zero headaches. Give it a try next time you’re juggling multiple things — you’ll wonder how you worked without it.

Toggle theme (T)