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

The Problem With Working on One Branch at a Time

When you’re deep into a feature branch and someone flags an urgent bug, you have two bad options: stash your work, switch branches, fix the bug, and context-switch back — or leave the bug sitting until you’re done. Neither is good.

Git worktrees solve this. And with Claude Code’s native git worktree support, you can run multiple AI-assisted coding sessions simultaneously on separate branches, each with its own working directory. No conflicts, no stashing, no mental overhead from switching contexts.

This guide covers how Claude Code git worktree support works, how to set it up from scratch, and how to structure parallel feature branch workflows that actually save time.

What Git Worktrees Actually Are

Git worktrees let you check out multiple branches from the same repository at the same time, each in its own directory. They share the underlying Git objects and refs — so they’re not separate clones — but each worktree has its own independent working directory, index, and HEAD.

Here’s the simplest mental model: your normal repository directory is the “main worktree.” When you add a linked worktree, Git creates a new directory on your filesystem where a different branch is checked out. You can have many linked worktrees, each on a different branch, all at once.

Why This Matters for Developers

Without worktrees, working on two things at once means either:

git stash, switch, work, switch back, git stash pop — annoying and error-prone
Cloning the repo twice — wastes disk space and loses shared history
Using workarounds that create drift between copies

Worktrees give you the best of both worlds: shared Git data, completely separate working directories. Git’s official documentation on worktrees covers the full command reference if you want to go deeper on the underlying mechanics.

How Claude Code Git Worktree Support Works

Claude Code is Anthropic’s terminal-based AI coding assistant. When you run it inside a git worktree, it recognizes the worktree context — the branch, the working directory, and the state of that specific checkout.

What this means practically: you can start separate Claude Code sessions in separate worktrees, and each session operates entirely within its own working directory. One Claude instance might be building a payment integration on feature/payments while another is refactoring the auth system on feature/auth-refactor. They don’t interfere with each other.

What “Native” Support Means

Prior to explicit worktree support, Claude Code could get confused when invoked from a linked worktree — it might incorrectly reference the main repository path, miss the branch context, or behave inconsistently. Native support means Claude Code:

Correctly identifies which worktree it’s operating in
Scopes its file operations to the correct working directory
Understands the branch context for things like suggesting commits, running tests, or referencing recent changes
Allows multiple simultaneous Claude Code processes without stepping on each other

This is particularly powerful because you’re not just parallelizing your manual work — you’re parallelizing AI-assisted work across multiple branches at the same time.

Setting Up Git Worktrees for Claude Code

Before running parallel Claude Code sessions, you need to set up the worktrees. Here’s how to do it.

Prerequisites

Git 2.5 or later (worktrees were introduced in Git 2.5)
Claude Code installed (follow Anthropic’s current installation instructions)
An existing Git repository

Step 1: Confirm Your Main Worktree

Start in your existing project directory. This is your main worktree:

cd /path/to/your-project
git status
# Confirm you're on your main branch (usually main or master)

Step 2: Add Linked Worktrees for Each Feature Branch

Use git worktree add to create a new worktree for each branch you want to work on:

# Create a worktree for a new feature branch
git worktree add ../your-project-payments feature/payments

# Create a worktree for another feature
git worktree add ../your-project-auth feature/auth-refactor

# If the branch doesn't exist yet, create it with -b
git worktree add -b feature/new-dashboard ../your-project-dashboard main

Each command creates a new directory alongside your main project folder with that branch checked out and ready to use.

Step 3: Verify Your Worktrees

Run git worktree list from any of the worktrees to confirm everything is set up correctly:

git worktree list
# Output:
# /path/to/your-project          abc1234 [main]
# /path/to/your-project-payments def5678 [feature/payments]
# /path/to/your-project-auth     ghi9012 [feature/auth-refactor]

Step 4: Launch Claude Code in Each Worktree

Navigate to each worktree directory and start Claude Code:

# In terminal window 1
cd ../your-project-payments
claude

# In terminal window 2
cd ../your-project-auth
claude

Each Claude Code session now operates in its own branch context. You can give each session a separate task — implement a feature, write tests, fix a bug — and they run concurrently without stepping on each other.

Running Parallel Feature Branches: Practical Workflows

Setting up worktrees is just the start. Here’s how to structure parallel development workflows that actually pay off.

Workflow 1: Feature Development + Bug Fix in Parallel

This is the most common use case. You’re mid-feature when a production bug appears.

Your setup:

Main worktree is on main
Linked worktree on feature/user-onboarding — active Claude Code session building a feature
A bug surfaces in production that needs immediate attention

Instead of interrupting your feature work:

# Create a hotfix worktree from main
git worktree add -b hotfix/login-error ../your-project-hotfix main

# Open Claude Code there
cd ../your-project-hotfix
claude
# Instruct Claude to investigate and fix the login error

Your feature branch stays untouched. Your hotfix branch gets Claude’s full attention. When the fix is done and merged, remove the worktree:

git worktree remove ../your-project-hotfix

Workflow 2: True Parallel Feature Development

Running two features simultaneously is where git worktree support pays off most for developers leaning heavily on Claude Code.

Worktree A (feature/payments): Claude Code is implementing Stripe integration
Worktree B (feature/notifications): Claude Code is building an email notification system
Main worktree: you’re reviewing PRs and merging

Each Claude session handles one task. You check in, give follow-up instructions, and run tests in each directory independently. One developer can effectively manage multiple parallel workstreams — something that was impractical before without aggressive context-switching.

Workflow 3: Code Review While Continuing Development

When you need to review a colleague’s branch without stopping your own work:

# Add a worktree for the PR branch you're reviewing
git worktree add ../your-project-review origin/feature/colleague-branch

# Use Claude Code to help with the review
cd ../your-project-review
claude
# Ask Claude to summarize the changes, flag potential issues, check test coverage

Claude can walk through the diff, identify potential problems, and suggest improvements — all while your own feature work continues in a separate session.

Managing Multiple Worktrees Without Losing Track

Running parallel Claude Code sessions creates a new organizational challenge: keeping track of what’s happening where. A few habits make this much easier.

Name Your Worktree Directories Clearly

Use descriptive names that match the branch purpose:

your-project/            # main worktree (main branch)
your-project-payments/   # feature/payments
your-project-auth/       # feature/auth-refactor
your-project-hotfix/     # hotfix/critical-bug

Avoid generic names like worktree-1 or branch-copy — you’ll lose track fast.

Name Your Terminal Tabs

Most terminal apps (iTerm2, Warp, Windows Terminal) let you name tabs. Name each tab after the worktree or branch it’s running. When you have three Claude Code sessions open, this makes switching between them much less disorienting.

Keep Worktrees Clean

Worktrees accumulate. Get into the habit of removing them when a branch is merged:

# List all worktrees
git worktree list

# Remove a specific worktree
git worktree remove /path/to/worktree

# Force remove if there are uncommitted changes (use carefully)
git worktree remove --force /path/to/worktree

# Clean up stale worktree references
git worktree prune

Syncing With Remote Changes

Each worktree operates on its own branch. To pull remote changes into a specific worktree:

cd /path/to/your-project-payments
git pull origin feature/payments

You can also fetch from the main worktree — since they share the same Git objects, a git fetch in any worktree updates the remote refs for all of them.

Common Issues and How to Fix Them

”Branch is already checked out”

This is the most common error when setting up worktrees. Git won’t let you check out the same branch in two worktrees at the same time.

fatal: 'feature/payments' is already checked out at '/path/to/other-worktree'

Fix: Create a new branch from the existing one rather than checking out the same branch again:

git worktree add -b feature/payments-v2 ../your-project-payments-v2 feature/payments

Claude Code Not Recognizing the Worktree Context

If Claude Code seems confused about the working directory or branch, check that you launched it from inside the worktree directory — not from the main repository path.

# Correct: launch from within the worktree directory
cd /path/to/your-project-payments
claude

# Potentially incorrect: launching from main and navigating elsewhere

File Watchers and IDE Conflicts

Some IDEs and file watchers don’t handle multiple worktrees well. They may try to index all worktrees as one project, causing conflicts or slowdowns.

Fix: Open each worktree as a separate project or window in your IDE. VS Code handles this well — just open the worktree folder as its own workspace.

Disk Space Buildup

Unlike separate clones, worktrees share Git objects — so the overhead is much smaller than cloning. But each worktree does have its own working copy of all files. If you have heavy build artifacts or node_modules, clean them up:

# In each worktree
rm -rf node_modules dist .next

Add these to .gitignore if they aren’t already.

Where MindStudio Fits Into AI-Assisted Development

If you’re running parallel Claude Code sessions with git worktrees, you’re already building a more AI-native development process. MindStudio extends that further — but at the workflow and integration layer rather than the code-editing layer.

The most direct connection is MindStudio’s Agent Skills Plugin — an npm SDK (@mindstudio-ai/agent) that lets AI agents call over 120 typed capabilities as simple method calls. Things like agent.sendEmail(), agent.searchGoogle(), agent.runWorkflow(), and agent.createDocument(). If you’re building an agent that needs to do more than write code — trigger a Slack notification when a branch is ready for review, send a test report by email, or call an external API as part of a development pipeline — the Agent Skills Plugin handles all that infrastructure so the agent can focus on reasoning, not plumbing.

On the platform side, MindStudio’s no-code visual builder lets you create AI-powered workflows that wrap and automate tasks around your development work: auto-generating PR descriptions from diffs, summarizing changelogs before a release, triaging incoming bug reports before they hit your backlog, or running code review checklists automatically. These are workflows you can build in minutes without writing a backend. You can find out more or start building for free at mindstudio.ai.

It’s not a replacement for Claude Code — it’s a complement. Claude Code handles the in-terminal, in-editor coding work; MindStudio handles the surrounding process automation that developers usually do manually.

Frequently Asked Questions

What is a git worktree and why should I use it with Claude Code?

A git worktree lets you check out multiple branches from the same repository into separate directories, all at the same time. With Claude Code’s native worktree support, you can run separate AI coding sessions in each worktree simultaneously — one Claude instance per branch, no conflicts. It’s useful when you need to work on multiple features or fixes without interrupting each other.

Can I run multiple Claude Code instances at the same time?

Yes. With git worktree support, each Claude Code session runs in a separate worktree directory with its own branch context. You can have two, three, or more Claude Code sessions active simultaneously, each working on a different branch. They operate independently and don’t interfere with each other.

Do git worktrees copy the entire repository?

No. Linked worktrees share the underlying Git object store with the main worktree. Only the working directory — the actual files on disk — is separate for each worktree. This makes worktrees much more efficient than cloning the same repo multiple times. The overhead is minimal compared to a full clone.

How is using a worktree different from just cloning the repo twice?

Cloning twice creates two entirely separate repositories. Changes, fetches, and merges in one don’t affect the other unless you manually sync them. Worktrees share the same Git data, so a git fetch in one worktree updates the remote refs for all of them. It’s faster, uses less disk space, and keeps everything in sync automatically.

Does Claude Code’s worktree support work on all platforms?

Claude Code runs on macOS, Linux, and Windows via WSL. Git worktrees are a Git feature rather than OS-specific, so they work wherever Git works. Claude Code’s worktree integration should behave consistently across platforms, though WSL users should make sure their directory paths are consistent within the Linux environment.

What happens if I forget to remove a worktree after merging a branch?

Nothing catastrophic — the worktree directory just stays on your filesystem. But stale worktrees pile up and cause confusion. Use git worktree list to see what’s active and git worktree remove to clean up. Running git worktree prune removes references to worktrees whose directories have already been deleted manually.

Key Takeaways

Git worktrees let you check out multiple branches simultaneously in separate directories, all sharing the same underlying Git repository.
Claude Code’s native git worktree support means you can run separate AI coding sessions in each worktree without conflicts or confusion about branch context.
Setup is straightforward: use git worktree add to create linked worktrees, then launch Claude Code from within each directory.
Parallel workflows — feature development, hotfixes, and code review — become practical when you’re not forced to switch branches or stash work mid-session.
Good hygiene matters: use clear directory names, remove worktrees after merging, and name your terminal tabs so you don’t lose track of what’s running where.
MindStudio’s Agent Skills Plugin and workflow builder can complement this setup at the process layer — automating the tasks surrounding development while Claude Code handles the code itself.

If you want to build AI-powered workflows that support your development process beyond individual coding sessions, try MindStudio for free.