How Git Worktrees Fix Multi-Instance Claude Code Chaos

The Problem: Shared Directories Cause Silent Data Loss

When you run multiple Claude Code instances against the same repository, you risk silent data loss. The root cause is simple: all instances share the same working directory. If Instance A has uncommitted changes and Instance B runs git pull --rebase, Instance A's work gets swept up and lost. If Instance C runs git stash, changes from A and B end up in C's stash, disappearing from their original context.

This isn't a theoretical issue—it's what happens when you scale Claude Code beyond a single instance. The traditional solution of carefully coordinating instances doesn't work with autonomous agents.

The Fix: Dedicated Worktree Per Instance

The solution is git worktree. Each Claude Code instance gets its own working directory and dedicated WIP branch, completely isolated from others.

Setup Script

Create .claude/scripts/setup-instance-worktree.sh:

#!/bin/bash
set -e

INSTANCE=$1
REPO_ROOT=$(git rev-parse --show-toplevel)
WORKTREE_DIR="$REPO_ROOT/.claude/worktrees/instance-$INSTANCE"
BRANCH="claude/${INSTANCE}-wip"

if [ -d "$WORKTREE_DIR" ]; then
  echo "worktree already exists: $WORKTREE_DIR"
  exit 0
fi

git worktree add "$WORKTREE_DIR" -b "$BRANCH" 2>/dev/null || \
  git worktree add "$WORKTREE_DIR" "$BRANCH"

echo "created: $WORKTREE_DIR (branch: $BRANCH)"

Usage:

bash .claude/scripts/setup-instance-worktree.sh ps1
bash .claude/scripts/setup-instance-worktree.sh vscode
bash .claude/scripts/setup-instance-worktree.sh win

This creates a structure like:

my_web_app/
  .claude/worktrees/
    instance-ps1/    ← branch: claude/ps1-wip
    instance-ps2/    ← branch: claude/ps2-wip
    instance-vscode/ ← branch: claude/vscode-wip

Key Configuration

Add worktrees to your local exclude file (not .gitignore):

# .git/info/exclude
.claude/worktrees/

View all active worktrees:

git worktree list

The Push Workflow: Direct to Main

Each instance works exclusively on its WIP branch and pushes directly to origin/main when ready. This is simpler than maintaining long-lived feature branches.

Recommended Push Pattern

From within the worktree directory:

git push origin HEAD:main

This pushes the currently checked-out branch to origin/main without needing to remember branch names.

Conflict Recovery (The 30-Second Fix)

When two instances push simultaneously, the second gets rejected. Recovery is one command:

git pull --rebase origin main && git push origin HEAD:main

Using rebase avoids merge commits and keeps your history clean.

Handling Specific Conflict Patterns

1. Simultaneous ROADMAP.md Appends

If every instance appends to docs/GROWTH_STRATEGY_ROADMAP.md at session end, you'll get constant conflicts.

Fix: Assign fixed sections per instance:

### PS版#1 Session Log

### PS版#2 Session Log

### VSCode Session Log

Instances never touch each other's sections, so rebase auto-merges succeed.

2. Migration File Timestamp Collision

When instances create Supabase migration files simultaneously:

20260419220000_seed_foo.sql   ← created by PS#1
20260419220000_seed_bar.sql   ← created by Win at the same second

Fix: Check current max timestamp before creating:

ls supabase/migrations/ | grep $(date +%Y%m%d) | sort | tail -1
# → 20260419220000_seed_foo.sql

# New file: +10 seconds
touch supabase/migrations/20260419220010_seed_bar.sql

3. WIP Branch Far Behind Main

After a long session, origin/main might be 20+ commits ahead.

Diagnosis:

git log --oneline claude/ps1-wip..origin/main | wc -l
# If 20+, inspect before rebasing

Fix for heavy conflicts:

git rebase --abort
git fetch origin
git merge origin/main  # accept the merge commit
# resolve conflicts manually
git push origin HEAD:main

Key Rules for Multi-Instance Success

1. Never work in the main repo directory — it's push target only
2. git stash is banned — WIP commit instead (git commit -m "WIP")
3. Commit before pull --rebase — staged-only changes can still be lost
4. Edit → commit → push in a single bash invoke — prevents linter revert interference

Results You Can Expect

git worktree isn't just a nice-to-have for multi-instance Claude Code—it's the design. One worktree + WIP branch per instance eliminates the entire class of "my changes disappeared" incidents.