# How Git Worktrees Fix Multi-Instance Claude Code Chaos

> A setup script and workflow for using git worktrees to safely run multiple Claude Code instances in parallel, with conflict recovery patterns.


## The Problem: Shared Directories Cause Silent Data Loss

![Mastering Git Worktrees with Claude Code for Parallel Development ...](https://miro.medium.com/v2/resize:fit:1358/format:webp/0*W4kalwsuzF8aOcZZ)


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`:

```bash
#!/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
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:
```bash
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:
```bash
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:
```bash
git pull --rebase origin main && git push origin HEAD:main
```

Using `rebase` avoids merge commits and keeps your history clean.

## Handling Specific Conflict Patterns

![How to Use Git Worktrees in Claude Code: Parallel AI ...](https://miro.medium.com/v2/resize:fit:1400/1*t52597u30NgJeIHMREo1Ig.jpeg)


### 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:
```markdown
### 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:
```bash
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**:
```bash
git log --oneline claude/ps1-wip..origin/main | wc -l
# If 20+, inspect before rebasing
```

**Fix for heavy conflicts**:
```bash
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

| Problem | Before | After |
|---------|--------|-------|
| stash interference | Changes from other instances disappear | **Each instance has its own stash** |
| `pull --rebase` | Sweeps up other instances' uncommitted work | **Only affects the local wip branch** |
| Parallel push | Collision / overwrite risk | **Always rebase-clean before push** |
| Debugging | Unclear which instance made a change | **Traceable by wip branch name** |

`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.


---
*Originally published on [gentic.news](https://gentic.news/article/how-git-worktrees-fix-multi)*