Running Claude Code Per Worktree: Notes From Actual Use

The Same Branch Cannot Be Checked Out Twice

This is the first constraint everyone meets.

$ git worktree add ../wt-dup main
fatal: 'main' is already checked out at '/home/me/demo'

Git is not being difficult. It is refusing to let two places move the same branch's HEAD. There are three ways around it:

1. Create a new branch for the worktree — ordinary feature work
2. Attach an existing, different branch — pulling a review down locally
3. Detach from any branch — read-only inspection

# 1. Grow a branch along with the worktree
git worktree add ../wt-hotfix -b hotfix/login-timeout origin/main
 
# 2. Lay out a colleague's branch for review
git worktree add ../wt-review review/pr-482
 
# 3. Inspect a tag without consuming a branch
git worktree add --detach ../wt-inspect v2.3.0

That third form earns its keep whenever I need to run shipped code locally to reproduce something. No branch is spent, so tearing it down later carries no hesitation.

Launching Claude Code Per Worktree

Here is the anticlimactic core of it: there is no special flag to learn. Claude Code works against the directory you launch it from, so moving into a worktree and starting it there is the isolation.

# Tab 1: feature work, left untouched
cd ~/projects/wt-feature-dashboard
claude
 
# Tab 2: the interruption, separate branch and directory
cd ~/projects/wt-hotfix-login-timeout
claude

Three things stood out once I had lived with this for a while.

• Conversation context accumulates per task — history builds per working directory, so picking up the next morning does not drag in an unrelated thread
• Permission memory does not transfer — .claude/settings.local.json is untracked, so a fresh worktree either asks again or gets the file from the script above
• CLAUDE.md can be overridden per worktree — a fix-only directory gets a short file saying exactly which paths are in scope

When a session genuinely needs to read another worktree, --add-dir grants that directory explicitly at launch. The flip side is the useful part: without it, nothing reaches sideways. That narrow default is what makes running two sessions feel safe.

One rule I hold firmly: never let two sessions edit the same file. Ownership is split by directory, and when a shared utility has to change for both, one side stops and the changes go in sequence. Parallelism buys back waiting time, not conflict resolution — something I learned properly after rewriting the same function twice and losing half a day to it.

How the Interrupted Friday Goes Now

Replaying that evening with the current setup:

1. Leave the unfinished work alone. Changing directories is the whole move
2. Run ./wt-new.sh hotfix/login-timeout to grow a worktree for the fix
3. Start Claude Code there, hand it the repro conditions and logs, narrow the cause
4. Test and build inside that worktree only, then push and open the PR
5. While review is pending, walk back to the original directory and keep building
6. Once merged, fold the worktree away and delete the branch

# 2. Grow it
./wt-new.sh hotfix/login-timeout
 
# 4. Verify inside that worktree alone
cd ../wt-hotfix-login-timeout
npm test && npm run build
git push -u origin hotfix/login-timeout
 
# 6. Fold it away
cd -
git worktree remove ../wt-hotfix-login-timeout
git branch -d hotfix/login-timeout

Step 5 is where the value actually shows up. The review window is not spent on a third context — it is spent returning to the work that got interrupted.

Cleanup: Leave No Prunable Entries

Deleting a worktree directory by hand leaves the registration behind, and the list drifts away from reality.

$ rm -rf ../wt-a
$ git worktree list
/home/me/demo  c88bbda [main]
/home/me/wt-a  dc6dc31 [feature/a] prunable
 
$ git worktree prune
$ git worktree list
/home/me/demo  c88bbda [main]

That prunable marker is your permission to clean. For a long-running investigation worktree, the opposite is useful — lock it so nothing removes it by accident.

$ git worktree lock ../wt-b --reason "reproducing a crash"
$ git worktree remove ../wt-b
fatal: cannot remove a locked working tree, lock reason: reproducing a crash
use 'remove -f -f' to override or unlock first

For scripted housekeeping, parse the machine-readable listing rather than the human one.

# Pull out paths and flag anything untouched for two weeks
git worktree list --porcelain \
  | awk '/^worktree /{print $2}' \
  | while read -r d; do
      [ -d "$d" ] || continue
      find "$d" -maxdepth 1 -mtime +14 -name .git -print
    done

Disk cost turned out smaller than I expected. On the repository I measured, .git totaled 308 KB and the admin files for one worktree came to 32 KB — roughly 10% of it. Unlike an extra clone, objects are never duplicated, so the only real growth is the source files themselves.

How Many Is Too Many

Early on I kept five worktrees open with a session in each. It went badly. Everything advanced halfway, and by the next morning I could not recall which directory was in the middle of what.

Two at a time is my limit now, three at the very most. The point of another worktree is to absorb waiting time, not to think about more things at once.

Add places to work, not places to decide. As long as the decision still happens in one spot, running things side by side stays safe.

When I am unsure, three questions settle it. Can I name what a directory is mid-way through, just from its name? If I stop now, can tomorrow's version of me resume? And is that task really blocked on waiting? A "no" to the third usually means the work belongs in a queue rather than a second worktree.

For the Next Interruption

Set up a single worktree now, before you need it, as the place to land when something urgent arrives. Even git worktree add --detach ../wt-inspect HEAD, which consumes no branch at all, noticeably lowers the friction of switching.

Since I stopped having to choose between unfinished work and a Friday-evening bug report, the weekends have felt considerably lighter. Thank you for reading.