What Is Claude Code Git Worktree Support? How to Run Parallel Feature Branches

The Context-Switching Tax Every Developer Pays

If you’ve used Claude Code for more than a few sessions, you’ve hit this wall: you’re deep into a feature branch, Claude has full context on what you’re building, and then an urgent bug or review request pulls you away. You switch branches, and suddenly Claude is working from a completely different codebase state — or you’re juggling terminal windows trying to keep everything straight.

Claude Code’s git worktree support is the direct fix for this. It lets you run parallel feature branches in separate working directories, each with its own Claude Code session, all pointing at the same repository. This guide explains what Claude Code git worktree support is, why it works the way it does, and how to actually use it.

What Git Worktrees Actually Are

Before getting into Claude Code specifics, it helps to understand the underlying git feature.

A git worktree is a linked working directory attached to an existing repository. By default, every repo has exactly one working directory — the one you cloned into. Git worktrees let you add more working directories, each with a different branch checked out, all sharing the same .git folder and object store.

This is different from cloning the repository again. With a clone, you’d have separate git histories that can diverge. With worktrees, you’re working against the same repository. Changes you commit in one worktree immediately show up in another (via the shared history), but the working files stay separate.

The Basic Git Worktree Commands

Creating a worktree is straightforward:

# Create a new worktree with an existing branch
git worktree add ../my-feature feature/my-feature

# Create a worktree with a new branch
git worktree add -b feature/new-thing ../new-thing main

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../my-feature

The first argument after add is the path to the new directory. The second is the branch name. Git creates the directory, checks out that branch, and links it back to your main repo.

One constraint worth knowing: the same branch can’t be checked out in two worktrees at the same time. Git enforces this to prevent conflicting edits to the same branch files.

How Claude Code Works With Git Worktrees

Claude Code operates from whichever directory you run it in. It reads your project structure, understands your codebase, and maintains context across your conversation about that directory’s contents.

When you run Claude Code inside a git worktree, it sees that branch’s state as the project. It doesn’t know about your other worktrees unless you tell it. This isolation is exactly what makes the workflow powerful.

Why Isolation Matters for AI-Assisted Coding

When Claude Code helps you on a feature branch, it’s building up context: what files changed, what the patterns are, what you’re trying to accomplish. If you switch branches mid-conversation, that context becomes unreliable. Claude might reference files that don’t exist on the new branch, or suggest patterns that belong to the old one.

With worktrees, you never switch branches inside a session. Each Claude Code instance lives in one directory, works on one branch, and keeps coherent context throughout. When you need to jump to a bug fix, you open a new terminal window in a different worktree — separate directory, separate Claude session, no cross-contamination.

Claude Code’s Worktree Awareness

Claude Code is designed to understand the git context of its working directory. When running inside a worktree, it correctly identifies:

The current branch name
The parent repository
The diff from the base branch
Which files are modified vs. untracked

This means Claude Code can accurately describe what’s changed in your branch, help write commit messages scoped to that branch’s work, and give advice without mixing up state from your other active branches.

Setting Up Parallel Feature Branches Step by Step

Here’s how to build a working parallel development setup with Claude Code and git worktrees.

Prerequisites

Git 2.5 or later (worktrees were added in 2.5; you almost certainly have this)
Claude Code installed (npm install -g @anthropic-ai/claude-code or via the Anthropic docs)
A git repository you’re actively working in

Step 1: Organize Your Worktree Directories

Pick a consistent location for your worktrees. A common convention is to put them alongside your main repo directory:

~/projects/
  my-app/           ← your main repo (main branch)
  my-app-feature-a/ ← worktree for feature/auth-redesign
  my-app-bugfix-123/ ← worktree for fix/issue-123

Or use a subdirectory inside the project:

~/projects/my-app/
  .git/
  src/
  worktrees/
    feature-auth/
    bugfix-123/

Either works. The key is picking something consistent so you’re not hunting for directories later.

Step 2: Create Your First Worktree

Navigate to your main repo directory and create a worktree for the feature you want to work on in parallel:

cd ~/projects/my-app

# Create a worktree from an existing remote branch
git worktree add ../my-app-feature-auth feature/auth-redesign

# Or create a worktree with a new branch off main
git worktree add -b feature/payment-flow ../my-app-payments main

Git will create the directory, check out the branch, and confirm with output like:

Preparing worktree (checking out 'feature/auth-redesign')
HEAD is now at a3f9d12 Add initial auth scaffolding

Step 3: Open Claude Code in Each Worktree

Open separate terminal windows for each worktree. In each one, navigate to the worktree directory and start Claude Code:

# Terminal 1 — main repo
cd ~/projects/my-app
claude

# Terminal 2 — auth feature
cd ~/projects/my-app-feature-auth
claude

# Terminal 3 — payment feature
cd ~/projects/my-app-payments
claude

Each claude instance is now isolated. You can work on the auth redesign in Terminal 2, switch to Terminal 3 to check on the payment flow, and neither session interferes with the other.

Step 4: Fetch and Sync Changes Between Worktrees

Since all worktrees share the same git history, you can fetch remote changes once and they’re available everywhere:

# From any worktree directory
git fetch origin

# Then in each worktree, rebase or merge as needed
git rebase origin/main

If your main branch gets updated, you don’t need to fetch separately in each worktree — one fetch handles all of them.

Practical Workflows You Can Build

The Interrupt-Driven Workflow

This is the most common use case. You’re actively coding on a feature when something urgent comes in — a production bug, a PR that needs review, a hotfix.

With worktrees:

Leave your feature branch Claude session running exactly as is.
Switch to a terminal window for the bugfix worktree (or create one).
Start a Claude session there, describe the bug, get it fixed.
Commit and push from the bugfix worktree.
Return to your feature branch — context is fully intact.

Nothing about your feature branch session changed while you were away. Claude still knows everything it knew before.

The Long-Running Feature Pattern

Some features take days or weeks. Traditionally, you’re constantly rebasing and stashing as you handle shorter-term work.

With a dedicated worktree for the long-running feature:

Keep it rebased on main periodically, but otherwise leave it alone.
Do all your shorter work in other worktrees or the main repo.
Return to the long-running feature with full context every time.

This is especially useful for large refactors, API migrations, or multi-part features where you need deep context each time you return.

The Parallel Experimentation Pattern

Not sure which implementation approach is better? Create two worktrees from the same base, try both with Claude Code’s help, and compare the results before committing to one direction.

git worktree add -b experiment/approach-a ../my-app-approach-a main
git worktree add -b experiment/approach-b ../my-app-approach-b main

Run Claude sessions in both, explore each approach, and when you’ve decided, delete the one you’re not using with git worktree remove.

The PR Review + Active Development Pattern

When a colleague’s PR comes in that you need to review carefully:

git worktree add ../my-app-pr-review origin/feature/their-branch
cd ../my-app-pr-review
claude

Ask Claude Code to walk you through the changes, identify potential issues, and suggest review comments — all without touching your own active development branch.

Tips for Managing Multiple Claude Sessions

Running multiple sessions in parallel is efficient, but it adds some cognitive overhead. A few habits that help:

Name your terminal tabs or panes. Most terminal apps let you name tabs. Something like [AUTH] or [BUGFIX-123] makes it obvious which session is which at a glance.

Be explicit about context at session start. When you open a Claude session in a worktree, start with a brief summary: “This is the auth redesign branch. We’re migrating from session tokens to JWTs.” Claude Code reads your files, but a quick orientation helps it respond faster and more accurately.

Don’t share state between sessions intentionally. The point of worktrees is isolation. If you need to move code between branches, use git cherry-pick or a proper merge — don’t try to copy-paste context between Claude sessions.

Keep your worktree list clean. Run git worktree list occasionally and remove worktrees for branches that have been merged:

git worktree remove ../my-app-old-feature
git branch -d feature/old-feature

Troubleshooting Common Issues

”fatal: ‘branch-name’ is already checked out”

This happens if you try to add a worktree for a branch that’s already checked out somewhere else. Either use a different branch name, or create a new tracking branch:

git worktree add -b feature/auth-v2 ../my-app-auth-v2 feature/auth

Claude Code Is Reading the Wrong Files

If Claude references files you don’t expect, double-check which directory you’re in with pwd. It’s easy to accidentally start Claude in your main repo when you meant to start it in a worktree.

Worktree Directory Already Exists

If the target directory already exists and has content, git will refuse to create the worktree there. Delete the directory first or choose a different path.

rm -rf ../my-app-old-worktree
git worktree prune  # cleans up metadata for removed worktrees

Performance on Large Repos

Worktrees don’t duplicate the .git folder or object store, so disk overhead is minimal. But if your repo has large node_modules or build artifacts, you’ll need those in each worktree separately. Add a quick setup step after creating a worktree:

cd ../my-app-new-feature
npm install

How MindStudio Fits Into an AI-Assisted Development Workflow

Claude Code handles the in-editor, in-terminal coding work well. But most development workflows extend beyond the terminal — there’s communication, documentation, testing coordination, deployment triggers, and more.

If you’re building AI-powered tools to support your development process, MindStudio is worth knowing about. It’s a no-code platform for building AI agents that can handle the surrounding workflow layer — things like automatically drafting PR descriptions from commit diffs, routing bug reports to the right team member, or summarizing changelog notes for each release.

For developers specifically, MindStudio’s Agent Skills Plugin (@mindstudio-ai/agent) is a practical tool. It’s an npm SDK that lets Claude Code and other AI agents call 120+ typed capabilities — agent.sendEmail(), agent.searchGoogle(), agent.runWorkflow() — as simple method calls. If you’re building agents that need to do more than write code (send notifications, query external APIs, trigger downstream processes), this handles the infrastructure layer so you’re not writing retry logic and auth handlers from scratch.

For teams running Claude Code across multiple worktrees on complex projects, having a workflow layer that handles communication and coordination can meaningfully reduce the back-and-forth overhead. You can try MindStudio free at mindstudio.ai.

Frequently Asked Questions

What is a git worktree?

A git worktree is an additional working directory linked to an existing repository. Unlike cloning a repo, worktrees share the same .git folder and commit history — they just let you have multiple branches checked out in different directories at the same time. You create one with git worktree add <path> <branch>.

Does Claude Code natively support git worktrees?

Yes. Claude Code operates based on the working directory it’s launched from. When you run claude inside a git worktree, it reads that directory’s branch state and builds its context from there. This means you can run separate Claude Code instances in separate worktrees simultaneously, each maintaining independent context about its own branch. Anthropic has recommended this as a pattern for parallel AI-assisted development.

How many worktrees can I run at once?

Git doesn’t impose a hard limit on the number of worktrees, and neither does Claude Code. In practice, the limit is your ability to track multiple contexts and your machine’s memory. Most developers work effectively with 2–4 active worktrees at a time — one for the main branch, one or two for active features, and potentially one for a bug fix or PR review.

What’s the difference between git worktrees and git stash?

Git stash saves your uncommitted changes to a temporary stack so you can switch branches — it’s a quick, temporary escape hatch. Worktrees are a persistent parallel structure where you never need to switch branches at all. With worktrees, both branches stay active and fully checked out simultaneously. Stash is good for quick interruptions; worktrees are better for sustained parallel work.

Can I use the same Claude session across multiple worktrees?

Not in a meaningful way. Each Claude Code session is tied to the directory it was started in. If you want Claude to understand code from a different worktree, you’d need to start a new session in that directory. This isolation is intentional and useful — it keeps Claude’s context clean and branch-specific.

Do git worktrees work with all git hosting services?

Yes. Worktrees are a local git feature and don’t depend on your hosting provider. They work identically whether your remote is GitHub, GitLab, Bitbucket, or a self-hosted server. You push and fetch branches the same way — the worktree just changes where those branches are checked out locally.

Key Takeaways

Git worktrees let you check out multiple branches in separate directories, all connected to the same repository, without duplicating the git history.
Claude Code is worktree-aware — running it inside a worktree directory gives it accurate, branch-specific context that stays isolated from your other sessions.
The setup is simple: git worktree add <path> <branch>, then start claude in each directory.
The biggest win is context preservation — you never lose an AI session’s context when an interruption pulls you to another branch.
Common patterns include: interrupt-driven workflows, long-running feature branches, parallel experimentation, and PR reviews alongside active development.

If you’re building tools that extend beyond the terminal — automating the communication, documentation, and coordination layer around your development workflow — MindStudio’s no-code agent builder and Agent Skills Plugin are worth exploring. The platform is free to start and takes most builders under an hour to get a working agent running.