Using Claude Code with Git Worktrees

1. Why git worktrees matter for Claude Code

Anyone wanting to work with Claude Code on several independent tasks at the same time quickly runs into a problem: a single working directory can only have one branch checked out at any given time. A git worktree solves exactly that by creating a second, third, or fourth independent working directory from the same repository, each with its own branch, but all accessing the same underlying git history. For Claude Code this means several sessions can work in parallel on different branches, without one session disturbing another through a branch switch.

The practical value shows up especially with tasks meant to run in parallel but requiring different code states: a hotfix on the production version while a large feature is being worked on in parallel on a different branch, or a code review pass on a pull request branch while one's own development continues undisturbed. Without git worktrees one would constantly need to switch between branches, with the risk of stashing unfinished changes or accidentally mixing them up.

2. Basics: worktree versus branch switching

A classic branch switch with git checkout or git switch changes the content of the same working directory, all files get swapped out, the previous state only continues to exist inside git itself. A git worktree, by contrast, creates a completely separate directory on disk, with its own, simultaneously checked out branch. Both directories share the same .git object directory in the background, so commits, branches, and the complete history stay visible between them without data needing to be duplicated.

The decisive difference from a full second clone of the repository: a git worktree shares the object database, whereas a second clone duplicates the complete history on disk. For a large repository with many years of history, this can make the difference between a few megabytes for an additional worktree and several gigabytes for a full second clone. This efficiency makes git worktrees the natural choice for temporary, parallel working directories.

3. Creating a worktree for a parallel task

The git worktree add command creates a new directory in one step and checks out a branch inside it, either an existing one or a newly created one. The path to the new directory should be clearly recognizable, for instance as a sibling directory of the main repository with the branch name in the path. Claude Code can then be started directly inside this new directory, with its own context, its own view of CLAUDE.md, and its own working state, completely independent from the main directory.

For a new task that has no branch yet, git worktree add -b creates a new branch and the associated worktree in a single command at the same time. This combination is especially handy for quickly starting parallel tasks: instead of first creating a branch and then manually switching there, the complete isolated working environment emerges in one step.

# Starting point: main repository at ~/projects/mironsoft
cd ~/projects/mironsoft

# Create a worktree for an existing branch (e.g. reviewing a PR)
git worktree add ../mironsoft-review-pr-42 origin/feature/checkout-redesign

# Create a worktree AND a new branch in one step (typical for a fresh task)
git worktree add -b feature/new-payment-method ../mironsoft-new-payment-method

# Start Claude Code inside the new, isolated worktree
cd ../mironsoft-new-payment-method
claude

4. Running several Claude Code instances at once

Because every git worktree is an independent directory, a separate Claude Code instance can be started inside each one, each with its own terminal window, its own conversation context, and its own working state. One instance can work on a hotfix while a second instance develops a new feature in parallel and a third reviews a pull request branch, all three fully independent of each other and without influencing one another.

This filesystem level parallelism is the central advantage over trying to juggle several tasks in a single Claude Code session through constant branch switching. Each instance consistently sees only the code state of its own branch, there is no confusion about which state is currently active, and an error in one instance, such as a broken build, does not affect the other instances in their own worktrees.

5. Isolating dependencies and build artifacts per worktree

A common trap when using several git worktrees: directories like node_modules or vendor are not version controlled by git and therefore exist separately in each worktree. This is fundamentally correct and necessary, since different branches can require different dependency versions, but it also means a separate installation step is needed after creating a new worktree, such as npm install or composer install, before the code is runnable.

For projects with very large dependency directories, a package manager with a global cache, such as pnpm or a shared Composer cache directory, is worth setting up across all worktrees. That way packages do not need to be downloaded completely fresh for every new worktree, only the symbolic links in the respective node_modules directory get recreated per worktree. This considerably reduces the time from creating a worktree to a first runnable environment.

#!/usr/bin/env bash
# setup-worktree.sh -- installs dependencies using a shared global cache
set -euo pipefail

WORKTREE_DIR="$1"
cd "$WORKTREE_DIR"

# Composer: shared cache directory across all worktrees, no re-download
composer config -g cache-dir "$HOME/.cache/composer-shared"
composer install --no-interaction

# npm/pnpm: pnpm's content-addressable store avoids duplicating packages
if [[ -f package.json ]]; then
  pnpm install --prefer-offline
fi

echo "Worktree at $WORKTREE_DIR is ready"

6. Listing, removing, and cleaning up worktrees

Over time, several git worktrees accumulate in an active project, so regular management matters. The git worktree list command shows all active worktrees with their path and checked out branch, so there is always an overview of which parallel working states currently exist. Once a task is finished and its branch merged, git worktree remove removes the directory cleanly, including the link inside git's internal metadata directory.

If a worktree directory gets accidentally deleted manually with rm -rf instead of using the correct command, an orphaned entry remains in git's internal bookkeeping. The git worktree prune command cleans up exactly such orphaned references and should be run routinely after manual cleanup to keep the internal worktree list consistent.

# List all active worktrees with their path and checked-out branch
git worktree list
# /home/user/projects/mironsoft            abc1234 [main]
# /home/user/projects/mironsoft-hotfix-88  def5678 [hotfix/TICKET-88]
# /home/user/projects/mironsoft-new-payment ghi9012 [feature/new-payment-method]

# Remove a worktree once its branch has been merged
git worktree remove ../mironsoft-hotfix-88

# Clean up stale references after a manual directory deletion
git worktree prune -v

7. Typical workflow: feature, hotfix, and review in parallel

A realistic daily routine with git worktrees and Claude Code often looks like this: the main work on a larger feature runs in the main directory on a feature branch. If an urgent production bug surfaces in the meantime, instead of a risky stash of the feature changes, a new worktree simply gets created for the hotfix branch, based on the current production tag. Claude Code works on the fix in this isolated directory while the feature progress in the main directory remains completely untouched.

In parallel, a third worktree can be created for an incoming pull request, to test its changes locally and review them in a structured way with Claude Code, without touching one's own working state at all. Once each of these three tasks is finished, the respective worktree gets removed while the other two continue unaffected. This pattern of feature, hotfix, and review in parallel is the most common practical use case for git worktrees in combination with Claude Code.

# A realistic day: feature work, an urgent hotfix, and a PR review, all in parallel

# Main directory stays on the feature branch, untouched
cd ~/projects/mironsoft   # branch: feature/checkout-redesign

# Urgent production bug arrives -- spin up an isolated hotfix worktree
git worktree add -b hotfix/TICKET-88 ../mironsoft-hotfix-88 origin/main
cd ../mironsoft-hotfix-88 && claude   # fix runs here, feature work untouched

# A PR needs review -- a third, read-mostly worktree
cd ~/projects/mironsoft
git worktree add ../mironsoft-review-pr-42 origin/feature/other-teammate-branch
cd ../mironsoft-review-pr-42 && claude   # review runs here

# All three working states coexist without interfering with each other
git worktree list

8. Pitfalls: shared .git directory and locking

Because all git worktrees of the same repository share the same internal object database, certain operations are not safely possible simultaneously across several worktrees. Two worktrees can never check out the same branch at the same time, git explicitly prevents this with an error message. Certain internal git operations like a rebase or an interactive history rewrite should also not run in one worktree while another worktree is simultaneously working on the same commits, because the referenced commit hashes could otherwise change during the ongoing operation.

A second practical pitfall is location: worktrees should live as sibling directories outside the main repository path, not as a subdirectory inside the main repository, otherwise git can mistakenly interpret the nested directory as part of the main repository's content. A third pitfall concerns IDE configuration and editor settings, which are often project specific but not part of the git repository, here a small setup script that automatically copies editor configuration files after creating a new worktree is worthwhile.

# Git explicitly refuses to check out the same branch in two worktrees
git worktree add ../mironsoft-second-copy feature/checkout-redesign
# fatal: 'feature/checkout-redesign' is already checked out at
#        '/home/user/projects/mironsoft'

# Correct: create a new branch from the same starting point instead
git worktree add -b feature/checkout-redesign-copy ../mironsoft-second-copy \
  feature/checkout-redesign

9. Worktrees compared with branch switching and cloning

For parallel work on several branches there are three fundamental approaches, whose pros and cons can be compared directly.

A second full clone offers the same isolation as a git worktree, but costs considerably more storage space and setup time, because the complete history gets duplicated. A simple branch switch is fastest to set up but prevents any form of parallel work across several branches at once. Git worktrees combine the advantages of both extremes: almost as lean as a simple branch switch, but with the full isolation of a second clone.

10. Summary

Git worktrees solve a concrete problem when using Claude Code on several parallel tasks: a single working directory can only check out one branch at a time, whereas a worktree creates an additional, fully isolated directory with shared git history. This allows several simultaneous Claude Code instances on different branches, each with its own context and its own working state, without branch switching endangering unfinished changes.

Dependencies like node_modules need to be installed separately per worktree, a global package cache considerably reduces the extra effort. Regular cleanup with git worktree remove and git worktree prune keeps management tidy. Compared to a full second clone, git worktrees are considerably leaner, compared to a simple branch switch they offer real parallelism without compromises.

11. FAQ: Using Claude Code with Git Worktrees