Parallele Claude-Code-Sessions mit git worktrees — zwei Branches gleichzeitig ohne Konflikt
Wie Du mit --worktree mehrere Claude-Code-Sessions parallel laufen laesst, ohne dass sich Feature und Bugfix gegenseitig die Files ueberschreiben. 10 Schritte mit Konfig, .worktreeinclude und Subagent-Isolation.
Du hast zwei offene Threads im Repo, ein Feature und einen Bugfix, beide brauchen Claude. Du startest zwei Terminals, in beiden claude und sofort schreiben beide Sessions in die gleichen Files. Plotzlich ändert die eine Session etwas das die andere gerade lesen wollte, der State ist hin. Genau dafür gibt es seit Claude Code v2.1.143 den --worktree-Flag. Jede Session bekommt ihr eigenes Working-Directory auf einem eigenen Branch und teilt nur die Git-History.
Das Pattern ist nicht neu, git worktree gibt es seit Git 2.5. Neu ist dass Claude Code das jetzt selber managed, inklusive Cleanup, Subagent-Isolation und Copy-Pattern für .env-Files. Ich nutze das seit 3 Wochen produktiv und kann pro Tag 2-3 Sessions parallel laufen lassen ohne Drift.
1. Vorraussetzung prüfen
Du brauchst Claude Code mindestens v2.1.143 und ein git-Repo. Check:
claude --version
# muss >= 2.1.143 zeigen, aktuell live ist 2.1.148
Wenn die Version älter ist, update vorher. Wir haben dafür ein eigenes Playbook unter Claude Code Update-Strategie. Ausserhalb eines git-Repos funktioniert --worktree nicht im Default-Modus, du brauchst dann einen WorktreeCreate-Hook für SVN/Mercurial/Perforce. Für 95 Prozent der Setups ist git der Default.
2. Repo-Trust einmalig akzeptieren
Beim ersten Aufruf in einem neuen Directory wirft Claude einen Workspace-Trust-Dialog. Der muss bestätigt sein BEVOR du --worktree benutzt, sonst exitet der Befehl mit einem Fehler. Also einmalig:
cd /pfad/zu/deinem/repo
claude
# Trust-Dialog akzeptieren, danach Session beenden
Dieser Schritt hat mich beim ersten Versuch 15 Minuten gekostet weil ich den Fehler nicht zuordnen konnte. --worktree sagt einfach "trust not accepted" und exitet, das steht so nicht auf der Stoerung.
3. .gitignore erweitern
Claude legt Worktrees standardmäßig unter .claude/worktrees/<name>/ an. Wenn du das nicht in .gitignore aufnimmst, tauchen alle Worktree-Inhalte als untracked Files im Main-Checkout auf und der Status wird unlesbar. Adde diese eine Zeile:
.claude/worktrees/
Das ist offiziell so empfohlen und ein One-Liner, also bitte nicht vergessen.
4. Ersten Worktree starten
Im Hauptverzeichnis deines Repos:
claude --worktree feature-auth
Claude legt jetzt .claude/worktrees/feature-auth/ an, branched von origin/HEAD auf einen neuen Branch worktree-feature-auth und startet die Session in dem Directory. Du kannst Code editieren als wäre es ein normaler Checkout. Die Session ist komplett isoliert von deinem Main-Checkout.
Wenn du den Namen weglaesst (claude --worktree ohne Argument), generiert Claude einen Zufallsname wie bright-running-fox. Praktisch für schnelle Experimente, unpraktisch wenn du den Worktree morgen wiederfinden willst. Ich empfehle: gib immer einen Namen.
5. Zweiten Worktree parallel öffnen
Zweites Terminal, gleicher Repo-Pfad, anderer Name:
claude --worktree bugfix-123
Jetzt laufen zwei Sessions parallel. Beide haben ihr eigenes Files-Subset, beide schreiben auf einen eigenen Branch, sie kommen sich nicht ins Gehege. Wenn du in Session 1 eine Datei änderst und in Session 2 die gleiche Datei aufmachst, siehst du in Session 2 den unveraenderten Zustand der Datei aus dem Branch-Base. Genau das war das Ziel.
6. .worktreeinclude für .env-Files
Standardmaessig ist ein Worktree ein frischer Checkout, also fehlen alle gitignored Files. Deine .env, .env.local, lokale Configs, Secrets, alles weg. Das führt dazu dass deine App im Worktree nicht startet weil keine DB-URL gesetzt ist.
Lösung: lege im Repo-Root eine Datei .worktreeinclude an, gleiche Syntax wie .gitignore. Beispiel:
.env
.env.local
config/secrets.json
Diese Files werden bei jedem --worktree-Call in den neuen Worktree kopiert, vorausgesetzt sie sind gitignored (tracked Files werden nie dupliziert). Mein Tipp: schreibe das .worktreeinclude direkt beim ersten Worktree-Setup, sonst hast du in 4 Wochen das Problem dass dein neuer Worktree ohne .env startet und du brauchst 20 Minuten bis du verstanden hast warum.
7. Subagent-Isolation aktivieren
Wenn deine Session Subagents spawned (du hast einen Subagent für Tests, einen für Lint, einen für Doku), können die parallel laufenden Subagents in deine Files schreiben und sich gegenseitig ueberschreiben. Lösung: lass Subagents in eigenen Worktrees laufen.
Variante A (per Session): sag in der Session "use worktrees for your agents". Claude packt jeden Subagent in einen temporaeren Worktree.
Variante B (permanent für einen Custom-Subagent): adde im Frontmatter des Subagent-Files:
---
name: test-runner
isolation: worktree
---
Subagent-Worktrees werden automatisch entfernt wenn der Subagent ohne Änderungen fertig ist. Wenn ein Subagent uncommitted Änderungen hat, fragt Claude beim Cleanup nach.
Wir haben das Subagent-Pattern auch in einem eigenen Playbook erklärt: Erster Sub-Agent in 30 Minuten.
8. Base-Branch konfigurieren
Worktrees branchen by default von origin/HEAD, also vom Remote-Main. Das ist sauber, du startest immer vom letzten gepushten Stand. Manchmal willst du aber von deinem lokalen HEAD branchen, etwa wenn du auf einem Feature-Branch sitzt und einen Subagent darauf isolieren willst. Setze in ~/.claude/settings.json oder im Project:
{
"worktree": {
"baseRef": "head"
}
}
Erlaubt sind nur "fresh" (Default, von origin/HEAD) und "head" (von lokalem HEAD). Du kannst keinen beliebigen Git-Ref angeben. Wenn du das brauchst, nimm manuelles git worktree add (Schritt 10).
9. Worktree für einen PR aufmachen
Habe ich erst letzte Woche entdeckt und finde ich genial. Du willst ein Pull Request reviewen, code reproduzieren oder anpassen:
claude --worktree "#1234"
Claude fetched pull/1234/head von origin und legt den Worktree unter .claude/worktrees/pr-1234 an. Du kannst auch die volle GitHub-PR-URL uebergeben. Spart das manuelle git fetch + worktree add + checkout-Geklimper.
Passt gut zu unserem Pull Request Reviews mit Claude Code Playbook.
10. Cleanup und manuelles Management
Wenn du die Session sauber beendest und keine Änderungen vorgenommen hast, raeumt Claude Worktree und Branch automatisch weg. Wenn es Änderungen oder Commits gibt, fragt Claude nach: Worktree behalten (default) oder loeschen.
In Non-Interactive-Runs (claude -p ohne Terminal) wird nicht aufgeraeumt, weil kein Prompt möglich ist. Da musst du selber ran:
git worktree list
# zeigt alle aktiven Worktrees
git worktree remove .claude/worktrees/feature-auth
# entfernt einen
Manuelle Variante ohne den --worktree-Flag, wenn du volle Kontrolle über Pfad und Branch willst:
git worktree add ../mein-projekt-feature-a -b feature-a
cd ../mein-projekt-feature-a
claude
Vergiss nicht: jeder Worktree ist ein frischer Checkout, also brauchst du einmalig npm install, pnpm install, python -m venv oder was auch immer dein Setup verlangt. Ich habe mir dafür ein kleines Shell-Script geschrieben das nach dem Worktree-Create automatisch pnpm install ausführt, das spart pro Worktree 2 Minuten.
Was als nächstes
Wenn du den Worktree-Workflow drauf hast, lohnt sich der Sprung zu echten parallelen Agent-Teams. Das wird interessant wenn du nicht nur Files isolierst sondern auch Coordination zwischen mehreren Claude-Sessions brauchst. Unser Playbook Erster Sub-Agent in 30 Minuten ist der Einstieg, danach lohnt sich Hooks gegen Halluzinationen als nächster Schritt um den Worktree-Lifecycle abzusichern.
Wenn du mit dem git worktree-Befehl noch nichts gemacht hast, gibt es bei uns auch eine sanfte Einführung in Git für KI-Workflows: Git für KI Quickstart.
Source
Offizielle Anthropic-Doku: https://code.claude.com/docs/en/worktrees (Stand 2026-05-22). Settings-Referenz für worktree.baseRef: https://code.claude.com/docs/en/settings. Manuelle Worktree-Verwaltung via Git: https://git-scm.com/docs/git-worktree.