Claude Code Git Worktrees: How to Run Parallel Feature Branches with AI

Why Switching Branches Mid-Task Is Costing You More Than You Think

If you’re using Claude Code for AI-assisted development, you’ve probably hit this wall: you’re deep into a feature, Claude has built up context about your codebase, and then something urgent comes up on another branch. You stash your changes, switch branches, lose your place, and start over.

The context switch isn’t just annoying — it’s a real productivity drain. And when you’re working with an AI coding assistant like Claude Code, that context matters even more. Every time you start a new session, Claude Code has to re-read the project to understand where things stand.

Git worktrees solve this. And Claude Code’s native support for working across worktrees means you can run multiple Claude Code instances simultaneously, each focused on a different feature branch, without ever losing context.

This guide covers exactly how to set that up.

What Git Worktrees Actually Do

Git worktrees are a built-in Git feature, but a lot of developers haven’t used them. The standard workflow is: one repository, one checked-out branch, one working directory at a time.

Worktrees break that constraint. They let you attach multiple working directories to a single repository. Each working directory has its own branch checked out independently — but they all share the same .git folder and commit history. No duplicate repos, no diverging histories.

Here’s the mental model: imagine your repository is the source of truth, and worktrees are separate views into that repository, each looking at a different branch simultaneously.

A typical setup might look like:

~/projects/
├── myapp/                    # Main repo + main branch
├── myapp-feature-auth/       # Worktree: feature/auth-overhaul
├── myapp-feature-dashboard/  # Worktree: feature/dashboard-redesign
└── myapp-bugfix-payments/    # Worktree: hotfix/payment-bug

All four directories pull from the same Git history. Changes committed in any one of them are immediately visible to the others (as commits, not as live file changes). You’re not duplicating your entire codebase — Git is smart about sharing objects between worktrees.

This is the foundation that makes parallel Claude Code sessions possible.

How Claude Code Handles Worktrees Natively

Claude Code is directory-aware. When you run claude in a directory, it reads the project structure from that location, understands the files present, and operates within that context. If that directory is a Git worktree, Claude Code works in the worktree — meaning it sees the branch that worktree has checked out, not the main branch.

This is what “native worktree support” means in practice: you don’t need special flags or configuration to make Claude Code work in a worktree. You run it in the worktree directory, and it just works in that branch’s context.

What makes this powerful is that you can run multiple Claude Code instances — one per worktree — and each instance operates completely independently. They don’t share sessions. They don’t interfere with each other’s file edits. They can each receive separate instructions and work on separate problems at the same time.

A few things that make this practical:

Independent contexts: Each Claude Code instance reads only the files in its worktree directory. It won’t accidentally edit files in a sibling worktree.
Shared Git history: Claude Code can use git log, git diff, and other Git commands within any worktree and get accurate, branch-specific results.
CLAUDE.md per worktree: You can put a CLAUDE.md file in each worktree directory to give that specific Claude Code instance task-specific instructions. More on this below.

Setting Up Git Worktrees for Parallel Development

Step 1: Create Your Worktrees

Start from your main repository directory. Create a worktree for each branch you want to work on simultaneously.

# Make sure you're in your main repo
cd ~/projects/myapp

# Create a worktree for an existing branch
git worktree add ../myapp-feature-auth feature/auth-overhaul

# Create a worktree and a new branch at the same time
git worktree add ../myapp-feature-dashboard -b feature/dashboard-redesign

# Create a worktree for a hotfix from main
git worktree add ../myapp-bugfix-payments -b hotfix/payment-bug origin/main

The first argument to git worktree add is the path where the new working directory should be created. The second is the branch — either an existing one or a new one (with -b).

To see all your active worktrees:

git worktree list

Output looks something like:

/Users/you/projects/myapp                   abc1234 [main]
/Users/you/projects/myapp-feature-auth      def5678 [feature/auth-overhaul]
/Users/you/projects/myapp-feature-dashboard 9ab0123 [feature/dashboard-redesign]
/Users/you/projects/myapp-bugfix-payments   456cdef [hotfix/payment-bug]

Step 2: Add CLAUDE.md Files for Task Context

One of the most useful Claude Code features for worktree workflows is the CLAUDE.md file. When Claude Code starts in a directory, it reads CLAUDE.md as a set of project-level instructions.

You can use this to give each worktree a specific focus. For example:

~/projects/myapp-feature-auth/CLAUDE.md:

## Task: Auth Overhaul

You are working on the authentication refactor (feature/auth-overhaul branch).

Key goals:
- Replace the legacy JWT implementation in /src/auth/
- Migrate users to the new session model
- Update all tests in /src/auth/__tests__/

Do not modify files outside of /src/auth/ and /src/users/ unless necessary.

~/projects/myapp-bugfix-payments/CLAUDE.md:

## Task: Payment Bug Fix

You are working on hotfix/payment-bug. This is a production issue.

The bug is in /src/services/PaymentService.ts — the `processRefund` method
is not handling partial refund edge cases. Fix only what's broken. Do not
refactor unrelated code.

These files persist in the worktree directory and load automatically every time you start Claude Code there. You only have to write them once.

Step 3: Open Multiple Terminal Sessions

To run Claude Code instances in parallel, you need multiple terminal sessions — one per worktree.

The simplest approach is multiple terminal tabs or windows:

# Terminal 1
cd ~/projects/myapp-feature-auth
claude

# Terminal 2
cd ~/projects/myapp-feature-dashboard
claude

# Terminal 3
cd ~/projects/myapp-bugfix-payments
claude

Each terminal runs a completely independent Claude Code session.

If you prefer keeping everything in one terminal, tmux is the standard tool for this. You can create named sessions for each worktree:

# Create named tmux sessions for each worktree
tmux new-session -d -s auth -c ~/projects/myapp-feature-auth
tmux new-session -d -s dashboard -c ~/projects/myapp-feature-dashboard
tmux new-session -d -s payments -c ~/projects/myapp-bugfix-payments

# Switch between them
tmux attach-session -t auth
tmux attach-session -t dashboard

Once you’re in a tmux session, start Claude Code with claude and work normally. Switch between sessions with Ctrl+B d to detach and then tmux attach-session -t <name> to reattach.

Running Claude Code in Parallel: Two Modes

Once your worktrees are set up, there are two main ways to use Claude Code across them.

Interactive Mode (Multiple Sessions)

The simplest approach: open Claude Code in each worktree and give each instance instructions interactively. You work across multiple windows, checking progress and providing feedback to each instance as it works.

This works well when:

Tasks require ongoing back-and-forth
You want to review each step before Claude continues
Tasks are complex enough to need human judgment mid-task

Non-Interactive Mode (Fully Autonomous)

Claude Code supports a non-interactive mode where you pass instructions directly at startup. This is useful when you want to fire off tasks and let Claude Code work autonomously while you focus elsewhere.

# Give Claude Code a complete task at startup and let it run
cd ~/projects/myapp-feature-auth
claude -p "Implement the auth overhaul described in CLAUDE.md. Run the test suite after each major change and fix any failures before moving on."

# In another terminal
cd ~/projects/myapp-bugfix-payments
claude -p "Fix the partial refund bug in PaymentService.ts. Write a test that reproduces the issue first, then fix it."

Both instances run at the same time. You can monitor their output, or leave them and come back when they’re done.

Non-interactive mode is especially powerful for well-defined tasks with clear success criteria (like “make all tests pass” or “implement the spec in this file”).

Practical Workflow Patterns

Pattern 1: Feature + Review Loop

While Claude Code works on a feature in one worktree, keep the main branch or a review worktree open. When Claude Code marks a task complete, you review the diff directly from the worktree directory without touching your other work.

# While Claude works on feature/auth-overhaul in myapp-feature-auth,
# review completed work in the same directory without switching branches
cd ~/projects/myapp-feature-auth
git diff main...feature/auth-overhaul

Pattern 2: Bug Fix While Feature Continues

A production bug comes in while Claude is 90% done with a feature. Instead of interrupting that session:

# Create a hotfix worktree from main
git worktree add ../myapp-hotfix-critical -b hotfix/critical-bug origin/main

# Start a new Claude session just for the hotfix
cd ../myapp-hotfix-critical
claude -p "Fix the bug described in issue #342. Add a regression test."

The feature session continues uninterrupted. The hotfix session runs in parallel. When the hotfix is done, merge it to main and delete the worktree.

Pattern 3: Parallel Exploration

Sometimes you want to try two different approaches to the same problem. Worktrees make this easy.

git worktree add ../myapp-approach-a -b experiment/approach-a
git worktree add ../myapp-approach-b -b experiment/approach-b

# Claude Code tries approach A
cd ../myapp-approach-a && claude -p "Implement the caching layer using Redis."

# Claude Code tries approach B
cd ../myapp-approach-b && claude -p "Implement the same caching layer using in-memory LRU cache."

Compare the two implementations, pick the better one, and delete the other worktree.

Cleaning Up Worktrees

When you’re done with a worktree, remove it cleanly:

# Remove a specific worktree
git worktree remove ~/projects/myapp-feature-auth

# If the worktree has untracked files you want to force-remove
git worktree remove --force ~/projects/myapp-feature-auth

# Prune references to any worktrees that were deleted manually
git worktree prune

Common Issues and How to Fix Them

”Branch is already checked out”

Git won’t let you check out a branch that’s already active in another worktree. If you try to create a worktree for a branch that’s currently checked out somewhere else, you’ll hit this error.

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

Fix: Use a different branch, or remove the other worktree first.

Node Modules and Environment Issues

Each worktree is a separate directory, so if your project uses node_modules, each worktree needs its own installed dependencies.

# After creating a worktree, install dependencies before running Claude Code
cd ~/projects/myapp-feature-auth
npm install
claude

For Python projects, create a virtual environment in each worktree directory, or use environment managers like pyenv or conda that can handle multiple environments cleanly.

Claude Code Reading the Wrong Files

If Claude Code seems confused about which branch it’s on, check that you’re in the correct worktree directory before starting the session. Running git branch in the worktree directory should show the branch that worktree has checked out.

Also make sure your CLAUDE.md is in the worktree root, not the main repo root — the worktree’s root is what Claude Code uses as its working directory.

Merge Conflicts from Parallel Work

When multiple Claude Code sessions modify files that share code (like utility modules or shared types), you can end up with merge conflicts. A few things help prevent this:

Scope each Claude Code session tightly using CLAUDE.md instructions that specify which directories are in scope
Merge from main frequently to keep worktree branches up to date
Use git fetch and git merge main (or git rebase main) in each worktree periodically

Extending Parallel AI Workflows Beyond the Terminal

Claude Code handles the coding side well. But real development workflows include more than just writing code — there are notifications, deployment triggers, documentation updates, external API calls, and team communication.

This is where MindStudio’s Agent Skills Plugin becomes useful. The @mindstudio-ai/agent npm SDK lets any AI agent — including Claude Code — call 120+ typed capabilities as simple method calls. Things like agent.sendEmail(), agent.searchGoogle(), agent.runWorkflow(), or agent.sendSlackMessage().

If you’re running parallel Claude Code sessions and want them to notify a Slack channel when a task is complete, trigger a CI/CD deployment, or update a project tracker automatically, you can wire that up through the SDK without building the infrastructure yourself. The plugin handles rate limiting, retries, and auth.

For teams running complex parallel development workflows — especially where AI agents are doing autonomous work across multiple branches — this fills the gap between “Claude Code commits the code” and “the rest of the team knows it’s ready.”

You can start using MindStudio free at mindstudio.ai.

Frequently Asked Questions

How many Git worktrees can you have at once?

Git doesn’t impose a hard limit on the number of worktrees. In practice, the constraint is your machine’s memory and CPU, especially if each worktree has Claude Code running in it. Most developers find 3–5 parallel worktrees is a practical upper bound before context-switching overhead between terminals becomes its own problem. For larger parallelism, a CI/CD setup or agent orchestration framework makes more sense than managing them manually.

Does Claude Code remember context between worktree sessions?

No. Each Claude Code session starts fresh. The CLAUDE.md file provides persistent instructions that load at session start, but there’s no memory of previous sessions by default. If you want Claude Code to know the history of what it worked on in a previous session, you need to provide that context explicitly — either in CLAUDE.md or in your initial prompt. Some teams keep a PROGRESS.md file in each worktree that they update manually (or have Claude Code update) with session notes.

Can two Claude Code instances edit the same file at the same time?

Technically yes, but you shouldn’t let them. If two worktrees contain the same file (shared utilities, for example) and two Claude Code instances edit it simultaneously, you’ll have a merge conflict when you try to integrate those branches. Prevent this by scoping each Claude Code session’s work carefully — use CLAUDE.md to specify which directories each instance should work in, and avoid having overlap in the files each worktree’s Claude Code session touches.

What’s the difference between a Git worktree and just cloning the repo twice?

A cloned repository is a complete, independent copy. It has its own .git directory, its own remote tracking, and its own complete object store. Worktrees share the parent repository’s .git folder and object store. This means they’re faster to create, take up less disk space, and stay automatically in sync in terms of commit history. Changes you commit in a worktree are immediately visible as commits to all other worktrees. With two separate clones, you’d need to push and pull to share commits.

Does this work with GitHub Codespaces or remote development environments?

Yes, with some caveats. Git worktrees work in any environment where Git is available. If you’re using GitHub Codespaces, each worktree will still create a separate directory inside your codespace container. You can run multiple Claude Code terminals in a codespace. The main limitation is that remote environments often have resource caps, so running many parallel Claude Code instances might hit memory or CPU limits faster than on a local machine.

Can I use Git worktrees with a monorepo?

Yes, and this is actually one of the better use cases for worktrees in large codebases. In a monorepo, different packages or services might be worked on simultaneously by different branches. Worktrees let you have feature/service-a-overhaul and feature/service-b-redesign checked out at the same time, with Claude Code working on each independently, even though both branches originate from the same monorepo. Just be aware that shared packages modified in one worktree’s branch may create conflicts when the other branch merges.

Key Takeaways

Git worktrees let you check out multiple branches simultaneously in separate directories, all sharing the same Git history and .git folder.
Claude Code works in worktrees natively — run claude in any worktree directory and it operates in that branch’s context without additional configuration.
CLAUDE.md files scoped to each worktree let you give each Claude Code instance task-specific instructions that load automatically at session start.
Non-interactive mode (claude -p "...") lets you kick off autonomous Claude Code tasks in multiple worktrees and work on other things while they run.
The main practical limits are machine resources and merge conflicts from overlapping file edits — scope each session carefully to avoid both.
MindStudio’s Agent Skills Plugin extends parallel AI coding workflows by giving Claude Code instances access to external actions (notifications, deployments, API calls) through a simple SDK.

If you’re doing meaningful development work with Claude Code, this setup is worth the 15 minutes it takes to configure. You’ll spend less time switching contexts and more time reviewing completed work across multiple branches simultaneously.