DEV Community

gentic news
gentic news

Posted on • Originally published at gentic.news

How Git Worktrees Fix Multi-Instance Claude Code Chaos

#ai #programming #opensource #machinelearning

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

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)"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Key Configuration

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

# .git/info/exclude
.claude/worktrees/
Enter fullscreen mode Exit fullscreen mode

View all active worktrees:

git worktree list
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Using rebase avoids merge commits and keeps your history clean.

Handling Specific Conflict Patterns

How to Use Git Worktrees in Claude Code: Parallel AI ...

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)