Claude Code and Git Worktrees: The Infrastructure for Parallel Development
Git branch switching is a bottleneck that most developers accept as a constant. Working on feature A, switching to fix a bug on feature B, switching back. Each switch involves stashing or committing work-in-progress, changing the working directory state, and re-establishing context. When Claude Code is involved, each switch also means ending one session and starting another.
Git worktrees eliminate this bottleneck. A worktree is a separate working directory linked to the same git repository, checked out to its own branch. Multiple worktrees can exist simultaneously, each on a different branch, each with its own Claude Code session. If you are new to Claude Code’s session model, the Claude Code Course covers the fundamentals before adding parallel workflows.
Feature A’s Claude Code session runs in one worktree. Feature B’s session runs in another. They do not interfere. No stashing, no switching, no lost context.
Worktrees are the foundation that makes parallel Claude Code sessions safe. Without them, parallel agents writing to the same branch produce conflicts. With them, each agent has an isolated workspace and the merges are clean.
What Git Worktrees Are
A git repository normally has one working tree: the directory where you see and edit files. Worktrees add more working trees to the same repository. Each additional worktree:
- Checks out a specific branch (or creates a new one)
- Lives in its own directory, separate from the main repository directory
- Shares the same git history and object store as the main repository
- Can be added, used, and removed without affecting other worktrees
The repository directory contains the full git history. Each worktree is an independently checked-out view of that history on a specific branch. Changes committed in one worktree become part of the shared git history and can be pulled into other worktrees through normal git operations.
This is different from cloning the repository. A clone creates a complete copy of the repository. A worktree adds a lightweight new working directory linked to the existing repository. Storage overhead is minimal: only the working directory files are duplicated, not the git object store.
Setup: Creating Worktrees for Claude Code Sessions
The git worktree add command creates a new worktree:
# Create a worktree for an existing branch
git worktree add ../project-feature-auth feature/auth-refactor
# Create a worktree and a new branch simultaneously
git worktree add -b feature/notification-service ../project-notifications mainThe first argument is the path where the new worktree will be created. Convention is to put worktrees as sibling directories to the main repository:
~/projects/
my-app/ # main repository
my-app-auth/ # worktree for feature/auth-refactor
my-app-notify/ # worktree for feature/notification-serviceOnce the worktree exists, open it in a new terminal tab and start a Claude Code session:
# Terminal 1: main repository
cd ~/projects/my-app
claude "fix the critical login bug"
# Terminal 2: auth worktree
cd ~/projects/my-app-auth
claude "refactor the JWT token handling module"
# Terminal 3: notifications worktree
cd ~/projects/my-app-notify
claude "build the email notification service"Three concurrent Claude Code sessions. Three isolated branches. No interference between them.
The Full Workflow: From Creation to Merge
Step 1: Create the worktree
git worktree add -b feature/payment-integration ../project-payments mainStep 2: Open the worktree and start Claude Code
cd ../project-payments
claude --plan "build the payment integration with Stripe"Use plan mode for the first session in a new worktree. Verify Claude Code understands the context before it starts writing.
Step 3: Work in the worktree
Claude Code operates normally within the worktree. It reads files, writes code, runs tests, and commits to the feature branch. All commits stay on feature/payment-integration and do not touch main or any other worktree’s branch.
Step 4: Finish the work and open a PR
git push origin feature/payment-integration
# Open pull request through GitHub/GitLabStep 5: Remove the worktree after merge
Once the PR is merged, clean up the worktree:
git worktree remove ../project-payments
git branch -d feature/payment-integrationClean removal keeps the repository organized. Stale worktrees that sit around after merge create confusion about what work is still in progress.
Worktree Operations Reference
| Operation | Command | When to use |
|---|---|---|
| Create worktree from existing branch | git worktree add <path> <branch> | Picking up existing feature work in new terminal |
| Create worktree with new branch | git worktree add -b <branch> <path> <start-point> | Starting new parallel feature |
| List all worktrees | git worktree list | Auditing active parallel sessions |
| Remove completed worktree | git worktree remove <path> | After PR merge or work abandonment |
| Prune stale worktree metadata | git worktree prune | After manually deleting worktree directories |
| Lock a worktree (prevent removal) | git worktree lock <path> | Long-lived shared worktrees in team environments |
Naming Conventions for Team Environments
Consistent naming makes it easy to understand what each worktree contains, who is working in it, and when it was created.
Recommended convention for solo use:
<repo-name>-<ticket-or-feature-slug>
my-app-auth-refactor
my-app-payment-integration
my-app-bug-1234Recommended convention for team use (when multiple developers work in the same repository):
<repo-name>-<username>-<feature-slug>
my-app-sarah-auth-refactor
my-app-james-payment-integrationThis prevents path collisions when two developers create worktrees for related features. Keep the path names under 40 characters to avoid shell escaping issues.
Branch naming should mirror the worktree path convention:
feature/sarah-auth-refactor
feature/james-payment-integrationClear naming creates a direct mapping: worktree path, branch name, and PR title all reference the same slug.
Using Worktrees With Parallel Claude Code Agents
The most powerful use of worktrees with Claude Code is as the foundation for parallel agent sessions. When the parent Claude Code session spawns parallel subagents, each subagent should operate in its own worktree:
Work on the following features in parallel using separate worktrees:
Feature 1 — Auth refactor:
- Worktree: ../project-auth
- Branch: feature/auth-refactor
- Task: Refactor JWT handling to use the new TokenService abstraction
Feature 2 — Notification service:
- Worktree: ../project-notify
- Branch: feature/notification-service
- Task: Build the email notification service per docs/notification-spec.md
Both worktrees already exist. Commit to each branch separately when complete.The worktrees must be created before spawning the parallel agents. Creating them is a 30-second setup step:
git worktree add -b feature/auth-refactor ../project-auth main
git worktree add -b feature/notification-service ../project-notify mainCommon Issues and Fixes
Worktree not recognized after manual directory deletion:
If you deleted the worktree directory without using git worktree remove, git still holds metadata for the stale worktree. Clean it up:
git worktree pruneDetached HEAD in the new worktree:
This happens when you create a worktree pointing to a commit hash rather than a branch name, or when the branch has been deleted. Fix by checking out a branch explicitly:
cd ../project-feature
git checkout -b feature/my-workPath conflict: worktree already exists at this path:
If a directory already exists at the worktree path, git will refuse to create the worktree there. Either remove the existing directory or choose a different path:
rm -rf ../project-feature-old
git worktree add ../project-feature feature/my-workCannot check out the same branch in two worktrees:
Git prevents the same branch from being checked out in multiple worktrees simultaneously. This is a safety feature, not a bug. If you need to work on the same branch in two locations, create a new branch for one of them.
Claude Code editing wrong files after directory change:
If you change directories without restarting Claude Code, the session may still reference the previous working directory path. Restart the Claude Code session in the new working directory to ensure file paths resolve correctly.
Frequently Asked Questions
How many worktrees can I have active simultaneously?
There is no practical limit imposed by git. The limit is your machine’s available disk space (each worktree is a full working directory copy of tracked files) and your ability to manage parallel sessions without losing track of what each one is doing. Most developers find three to five active worktrees manageable. Beyond that, the coordination overhead of tracking parallel work outweighs the parallelism benefit.
Can I run the same test suite in two worktrees simultaneously?
Yes, with caveats. If the tests use shared external resources (a local database, a fixed port number, a shared temp directory), concurrent test runs will conflict. Use separate test database instances or port assignments for each worktree. Most modern test frameworks support environment-variable-based configuration for exactly this reason.
Do worktrees share node_modules or other build artifacts?
No. Each worktree has its own copy of untracked files. node_modules, build outputs, and .env files are separate in each worktree. This means you need to run npm install (or equivalent) in each new worktree before running the project.
It also means that a broken node_modules in one worktree does not affect others.
What happens to a worktree if I delete the parent repository?
Worktrees depend on the parent repository’s git object store. If the parent repository is deleted, worktrees become unusable (they cannot commit or fetch). Always remove worktrees before deleting or moving the parent repository.
Want to run parallel Claude Code sessions without conflicts?
Worktrees are a 30-second setup step that unlock a fundamentally different way of working, multiple isolated sessions, clean merges, no stashing or context-switching. The commands above are everything you need to get started.
Path one: set up worktrees yourself. The git worktree add command and the naming conventions in this article are all you need. Start with two parallel worktrees on your current project and verify the workflow before scaling to more.
The Claude Code course covers the session model that makes parallel workflows productive.
Path two: work with Phos AI Labs. If you want parallel Claude Code workflows designed for your team’s development process, including worktree conventions, branch strategy, and merge coordination, Phos AI Labs is a CCA-F certified Claude implementation partner that designs the infrastructure that makes AI-assisted development reliable. Thirty minutes, no deck. Start here.