Playbook· build

Mit Git Worktrees parallele Claude-Code-Sessions fahren

Wie du mehrere Branches gleichzeitig mit Claude Code bearbeitest, ohne in Stash-Hoelle zu enden. Ein Worktree pro Branch, eine Session pro Worktree, kein Wechseln.

Stash, Branch, Pull, "wait, was ist hier eigentlich los" — wer Claude Code im Daily-Driver-Modus benutzt, kennt den Effekt. Bug-Fix kommt rein während der Feature-Branch halb fertig ist. Drei Stashes stapeln sich. Reviewer schickt eine Änderung am alten PR, du musst kurz wechseln, vergisst aber dass im aktuellen Repo noch ein Edit offen ist. Git Worktrees lösen das, indem du jeden Branch in ein eigenes Verzeichnis legst. Eine Claude-Code-Session pro Verzeichnis. Kein Wechseln, kein Stashen, kein "wo war ich nochmal".

Dieses Playbook zeigt das Setup das ich seit über einem Monat fahre. Vier bis sechs Worktrees parallel sind realistisch. Eine pro aktiver Aufgabe.

Schritt 1: Verstehen was ein Worktree macht

Ein normales Git-Repo hat genau einen Working-Tree. Wenn du den Branch wechselst, ändert sich der Inhalt im selben Verzeichnis. Ein Worktree dagegen ist ein zusaetzliches Verzeichnis das mit dem gleichen .git-Datenbestand verbunden ist, aber einen eigenen Branch ausgecheckt hat. Vier Worktrees bedeuten vier Verzeichnisse, vier Branches gleichzeitig sichtbar, ein gemeinsamer Commit-Graph.

Das spart Plattenplatz, weil Git intern nur einmal die Objekte vorhaelt. Und es macht das Arbeiten mit Claude Code planbar, weil jede Session ein klar abgegrenztes Verzeichnis hat. Keine "warum hat sich der Code in meinem anderen Terminal-Tab verändert"-Momente.

Schritt 2: Verzeichnis-Layout entscheiden

Bevor du den ersten Worktree erstellst, leg ein Layout fest. Ich nutze:

~/projects/
  mein-projekt/                  # Hauptrepo, main-Branch
  mein-projekt-feat-auth/        # Worktree fuer Feature
  mein-projekt-fix-stripe/       # Worktree fuer Bugfix
  mein-projekt-pr-12/            # Worktree fuer PR-Review

Wichtig: keine Worktrees innerhalb des Hauptrepos. Das funktioniert technisch, aber Claude Code wird beim Indexieren irre. Nebeneinander ist sauber.

Schritt 3: Den ersten Worktree erstellen

Im Hauptrepo:

cd ~/projects/mein-projekt
git worktree add ../mein-projekt-feat-auth -b feat/auth

Das erstellt das neue Verzeichnis und legt gleichzeitig einen neuen Branch feat/auth an. Wenn du auf einem bestehenden Branch arbeiten willst, weil ein Reviewer dir was geschickt hat:

git worktree add ../mein-projekt-pr-12 origin/feat/payment-refactor

git worktree list zeigt dir jederzeit was du hast. Wenn du am Anfang verloren gehst, hilft das.

Schritt 4: Claude Code im Worktree starten

In jedem Worktree-Verzeichnis startest du eine eigene Claude-Code-Session. Mein Setup: ein iTerm-Tab pro Worktree, im Tab-Titel der Branch-Name. Bei VS Code analog mit Workspaces.

cd ~/projects/mein-projekt-feat-auth
claude

Wichtig zu wissen: Claude Code liest die CLAUDE.md aus dem aktuellen Working-Directory. Wenn dein Hauptrepo eine CLAUDE.md hat, hat der Worktree die auch, weil es derselbe Branch sein kann oder die Datei mitgemergt wurde. Änderungen an der Datei sind aber Branch-spezifisch. Das ist Feature, nicht Bug. Falls du eine Worktree-spezifische Instruktion willst, leg eine CLAUDE.local.md ins Worktree-Verzeichnis. Die git-ignorest du im .gitignore, und Claude Code zieht sie automatisch mit rein.

Schritt 5: Modelle pro Worktree variieren

Hier wird das Pattern wirklich nuetzlich. Jeder Worktree kann ein anderes Modell fahren. Ein Beispiel-Setup das ich aktuell habe:

mein-projekt/ (main, Hauptrepo) — Opus 4.7, für Architektur-Fragen und größere Refactors
mein-projekt-feat-auth/ — Sonnet 4.6, ein klar umrissenes Feature, mittlere Komplexitaet
mein-projekt-fix-stripe/ — Haiku 4.5, ein 30-Zeiler-Bugfix
mein-projekt-pr-12/ — Sonnet 4.6, weil ich den Review-Diff verstehen will

Das spart Kosten und gleichzeitig Latenz, weil Haiku-Anworten in unter zwei Sekunden zurückkommen während Opus auf der schwierigen Frage lang nachdenkt. Modellwahl pro Session während des Starts oder über /model im laufenden Chat.

Schritt 6: Den merge-back planen

Worktrees sind kein Ersatz für sauberes Branching. Wenn ein Feature fertig ist, mergest oder rebasest du den Branch zurück nach main wie immer. Mein Flow:

cd ~/projects/mein-projekt
git fetch origin
git merge --ff-only origin/main          # main aktuell halten
git merge --no-ff feat/auth              # oder rebase, je nach Repo-Policy

Solange der Worktree existiert, ist der Branch dort ausgecheckt und kannst du ihn im Hauptrepo nicht parallel auschecken. Das ist Absicht. Git verhindert hier Doppelarbeit.

Schritt 7: Worktree wieder loeschen

Wenn der Branch gemergt und der Worktree leer ist:

git worktree remove ../mein-projekt-feat-auth

Falls das Verzeichnis schon weg ist (z.B. mit rm -rf geloescht), bleibt im Hauptrepo der Worktree-Eintrag hängen. git worktree prune raeumt das auf. Einmal pro Woche reicht.

Schritt 8: Mit Subagent-Worktree-Isolation kombinieren

Wenn du Subagents fahren lässt, kannst du im Frontmatter eines Subagents isolation: "worktree" setzen. Das ist eine andere Ebene als das hier beschriebene User-Pattern. Der Subagent spawnt sich dann selbst in einen frischen, ephemeren Worktree, faehrt seinen Job, und wenn er fertig ist, mergt er den Diff zurück oder verwirft ihn. Du siehst diese Worktrees normalerweise nicht, weil sie Claude-Code-intern verwaltet werden.

Faustregel: User-Worktrees für Aufgaben die länger als eine Session dauern (Features, Reviews). Subagent-Worktrees für kurzlebige, isolierte Jobs (Code-Review, Refactor-Test). Beides darfst du parallel benutzen. Details zum Subagent-Pattern stehen im Playbook "Erster Sub-Agent in 30 Minuten".

Schritt 9: Stolperfallen die mich Zeit gekostet haben

Drei Sachen sind mir in den ersten zwei Wochen passiert:

Erstens: Node node_modules ist pro Worktree separat. Wenn du im Hauptrepo npm install machst, hat der Worktree nichts. Das ist konsistent mit Git-Verhalten, aber wenn du wechselst und vergisst zu installieren, kriegst du komische Errors. Lösung: pnpm mit node-linker=hoisted über alle Worktrees hinweg, oder einfach merken.

Zweitens: .env-Files sind in den meisten Repos in .gitignore. Heißt: dein neuer Worktree hat keine .env. Lösung: ein cp ~/projects/mein-projekt/.env ../mein-projekt-feat-auth/.env direkt nach git worktree add. Ich hab das als Shell-Function wta (worktree-add) gebaut die beides macht.

Drittens: Wenn dein Repo Submodules hat, bekommt der neue Worktree die nicht automatisch. git submodule update --init --recursive im neuen Verzeichnis löst das.

Schritt 10: Mit Memory-Hooks sauber zusammenfuehren

Wenn du Memory-Hooks oder eine eigene Skill nutzt die pro Projekt eine eigene Session-ID schreibt, achte darauf dass der Hook das Working-Directory korrekt erkennt. Branch-Name plus Worktree-Pfad reichen normalerweise als Session-Key. Bei mir landet jede Worktree-Session im selben Memory-Store, aber mit einem Tag der den Branch nennt. So sieht der Memory-Recall am nächsten Tag noch wo welcher Gedanke herkam.

Wenn dein Hook das nicht kann, ist das ein Hinweis dass die Hook-Logik veraltet ist und nur das Repo-Root kennt. Im Playbook "Memory drift reparieren" steht wie du das aktualisierst.

Was als nächstes

Wenn das Worktree-Setup läuft, ist der nächste sinnvolle Schritt entweder Subagents (Playbook "Erster Sub-Agent in 30 Minuten") oder, wenn du mit dem Git-Pattern noch unsicher bist, das Mini-Modul "Git für KI" in Level 1, speziell Lesson 9 zu Branches und Reviews. Wer das Pattern aufs Team übertragen will, findet im Playbook "Claude Code im Team — CLAUDE.md gemeinsam pflegen" die nächste Stufe.

Quellen

Git Worktree Doku: https://git-scm.com/docs/git-worktree
Subagent-Worktree-Isolation: siehe Recipe 3.3 Subagent Basics (Frontmatter-Feld isolation)

← Sub-Agent oder Skill oder MCP-Memory-Backup vor Update, dami→