Git-Worktree in Claude Code: parallele Sitzungen

Praktische Informationen zur Arbeit mit Ailoot findest du in der Dokumentation.

Was ist ein Git-Worktree in Claude Code?#

Mehrere Agents parallel im selben Ordner zu starten ist der grundlegende Schmerzpunkt von Vibe-Coding mit dem Tempo von 2026. KI-Agents schreiben Code schneller, als ein Mensch nachverfolgen kann, wer woran arbeitet. Ohne Dateisystemisolation endet der Start von zwei parallelen Claude-Code-Sitzungen in einem Verzeichnis damit, dass eine Sitzung die Arbeit der anderen überschreibt.

Git-Worktree löst das auf Dateisystemebene. Du hast ein Hauptverzeichnis, in dem du arbeitest. Der Befehl claude --worktree feature-auth erstellt den Ordner .claude/worktrees/feature-auth/ auf einem separaten Branch und startet Claude Code dort. Die Dateien sind isoliert. Änderungen in einer Sitzung sind für die andere nicht sichtbar, bis du sie ausdrücklich zusammenführst.

Die offizielle Anthropic-Dokumentation formuliert es so:

Ein Hinweis zur Selbstprüfung: Wenn du schon einmal einen Commit bekommen hast, bei dem die Hälfte der Dateien die Arbeit eines anderen war, brauchst du einen Worktree.

Wie sich Git-Worktree von einem regulären Branch unterscheidet#

Der standardmäßige Git-Ablauf: Du bist auf dem Branch main und führst git checkout feature-x aus – Git überschreibt die Dateien der Arbeitskopie. Ein laufendes npm run dev funktioniert nicht mehr, weil sich package.json darunter geändert hat. Du stashst deine nicht committeten Änderungen und wartest, bis die IDE neu indiziert hat. Du wechselst zurück, und alles wird erneut überschrieben; also musst du wieder stashen und poppen.

Git-Worktree bietet dir eine andere Möglichkeit: Statt einen Ordner zwischen Branches zu wechseln, erstellst du einen zweiten Ordner für einen anderen Branch. Der Befehl git worktree add ../project-feature-x feature-x erstellt das Verzeichnis ../project-feature-x/ mit den Dateien des Branchs feature-x. Dein main bleibt im ursprünglichen Ordner, und der Entwicklungsserver läuft weiter.

Früher musste der Worktree-Modus in Claude Code manuell eingerichtet werden: git worktree add, dann cd, dann claude – und das in jedem Terminal wiederholen. Das Flag --worktree (auch -w) erledigt alle drei Schritte mit einem Befehl.

Die erste parallele Sitzung starten: das Flag --worktree#

Minimales Beispiel. Öffne das erste Terminal im Projektstammverzeichnis:

claude --worktree feature-auth

Claude Code führt drei Schritte aus:

1. Erstellt .claude/worktrees/feature-auth/ mit einem Snapshot von origin/HEAD (normalerweise deinem Standard-Branch).
2. Erstellt einen neuen Branch worktree-feature-auth.
3. Startet die Sitzung in diesem Ordner.

Öffne ein zweites Terminal im selben Repository-Stammverzeichnis:

claude --worktree bugfix-123

Fertig. Zwei Claude-Code-Sitzungen, unterschiedliche Dateien auf der Festplatte, unterschiedliche Git-Branches. Wenn du in der ersten Sitzung Authentifizierung schreibst und in der zweiten einen fehlschlagenden Test reparierst, können sie sich physisch nicht in die Quere kommen.

Wenn du keinen Namen eingeben möchtest, denkt sich Claude einen aus:

claude --worktree
# → creates something like .claude/worktrees/bright-running-fox/

Ein Tipp für Git-Anfänger: Füge .claude/worktrees/ zu .gitignore hinzu. Andernfalls siehst du bei git status im Hauptordner den Inhalt aller Worktrees als nicht nachverfolgte Dateien:

# .gitignore
.claude/worktrees/

Eine Falle, die du vermeiden solltest: Bevor du --worktree zum ersten Mal in einem neuen Verzeichnis startest, öffne es mit einem regulären claude (ohne Flag) und bestätige den Dialog zum Vertrauen in den Arbeitsbereich. Wenn du das nicht tust, schlägt das Flag mit einem Fehler „trust not accepted“ fehl – auch wenn du es für den Headless-Modus mit -p kombinierst.

Wo Worktrees liegen und wie du sie findest#

Der Standardspeicherort ist festgelegt: .claude/worktrees/<value>/ im Stammverzeichnis des Repositorys. Wenn dein Projekt unter ~/dev/my-app/ liegt, befindet sich der Worktree feature-auth unter ~/dev/my-app/.claude/worktrees/feature-auth/.

Für ungewöhnliche Verzeichnisstrukturen (zum Beispiel, wenn du den Worktree außerhalb des Repositorys haben möchtest) gibt es den Hook WorktreeCreate – mehr dazu weiter unten im Abschnitt zu SVN und Mercurial.

Innerhalb einer Claude-Sitzung kannst du zu einem anderen vorhandenen Worktree wechseln. Schreib einfach im Chat: „switch to .claude/worktrees/bugfix-123“, und Claude ruft das Tool EnterWorktree auf. Der aktuelle Ordner bleibt unverändert – du kannst auf dieselbe Weise zurückkehren.

Der standardmäßige Git-Befehl zeigt eine Liste aller Worktrees an, einschließlich des Haupt-Worktrees und der manuell erstellten:

git worktree list

Die Ausgabe sieht etwa so aus:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

.env und Geheimnisse kopieren: die Datei .worktreeinclude#

Wenn --worktree einen neuen Ordner erstellt, enthält er nur das, was in Git committet wurde. .env mit API-Schlüsseln und .env.local mit lokaler Konfiguration stehen in .gitignore und befinden sich daher nicht im Worktree. Schon der erste Aufruf von npm run dev schlägt dann mit „MISSING DATABASE_URL“ fehl.

Die selbstgebastelte Lösung besteht darin, .env nach jedem --worktree manuell zu kopieren. Einmal klappt es, dann wird es vergessen. Anthropics Lösung ist die Datei .worktreeinclude im Projektstammverzeichnis, in der die von Git ignorierten Dateien stehen, die automatisch in jeden neuen Worktree kopiert werden sollen.

Erstelle eine Datei .worktreeinclude im Repository-Stammverzeichnis:

.env
.env.local
config/secrets.json

Die Syntax ist dieselbe wie bei .gitignore. Du kannst Glob-Muster verwenden:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic nennt eine klare Regel, um Unfälle zu vermeiden:

Anders gesagt: Du kannst package.json nicht versehentlich über .worktreeinclude kopieren – die Datei steht nicht in .gitignore. Es ist sicher, dort beliebige Muster einzutragen.

Dieselbe .worktreeinclude funktioniert in drei Modi: manuellem --worktree, automatischen Worktrees für Subagents (siehe unten) und Sitzungen in der Claude-Desktop-App.

Worktree aus einem Pull Request für Code-Reviews#

Ein typisches Code-Review-Szenario: Ein Kollege hat einen PR geschickt; du musst den Code prüfen, Tests ausführen und einen Kommentar hinterlassen. Mit einem regulären git checkout pull/1234/head wechselst du erneut die Arbeitskopie und unterbrichst deine aktive Sitzung.

Mit dem Flag --worktree genügt dafür ein Befehl:

claude --worktree "#1234"

Was passiert: Claude Code führt git fetch origin pull/1234/head aus, erstellt unter .claude/worktrees/pr-1234/ einen Worktree und checkt den PR-Branch aus. Die Sitzung startet. Du kannst sofort darum bitten, „den Diff zu lesen, die Tests auszuführen und logische Fehler zu finden“ – während Claude arbeitet, läuft deine Hauptsitzung auf main weiter.

Die alternative Schreibweise ist die vollständige Pull-Request-URL:

claude --worktree https://github.com/OWNER/REPO/pull/1234

Für ein echtes Projekt: Wenn du claude --worktree "#N" mit einem eigenen Code-Reviewer-Subagent kombinierst, erhältst du in ein bis zwei Minuten ein automatisches Review. Starte es im Hintergrund, arbeite im Hauptfenster weiter und rufe das Ergebnis über claude agents ab.

Basis-Branch: worktree.baseRef für fresh oder head#

Die Standardeinstellung lautet: Jeder neue Worktree startet von origin/HEAD. Der Vorteil ist ein sauberer Ausgangspunkt, der garantiert dem entspricht, was CI sehen wird. Der Nachteil: Wenn du nicht committete Änderungen oder mehrere lokale Commits über den Remote hinaus auf deinem aktuellen Branch hast, werden sie nicht in den neuen Worktree übernommen.

Damit ein Worktree vom aktuellen lokalen HEAD-Commit startet, ergänze in .claude/settings.json oder den globalen Einstellungen:

{
  "worktree": {
    "baseRef": "head"
  }
}

Nun startet claude --worktree experimental-feature vom aktuellen lokalen HEAD. Das hilft, wenn dein Feature bereits lokale, noch nicht gepushte Commits enthält. Noch nicht committete Änderungen erfasster Dateien fehlen weiterhin. Braucht der Subagent sie, sichere und übertrage die benötigten Änderungen ausdrücklich und prüfe anschließend den Zieldiff. Verwechsle diesen Schritt nicht mit .worktreeinclude, das ignorierte lokale Dateien behandelt.

Die Einstellung akzeptiert genau zwei Werte: "fresh" (= origin/HEAD) und "head" (= lokales HEAD). Beliebige Refs wie "feature-branch" oder ein Commit-Hash sind nicht erlaubt – dies ist eine bewusste Einschränkung, um eine kombinatorische Explosion von Optionen zu verhindern.

Subagents automatisch isolieren: isolation: worktree#

Wenn du Claude sagst: „Starte drei Subagents: Einer liest die Datenbank, der zweite schaut sich die API an und der dritte prüft die Tests“, arbeiten standardmäßig alle drei in deiner Arbeitskopie. Wenn auch nur zwei gleichzeitig dieselbe Datei ändern, entsteht ein Konflikt. Die Lösung besteht darin, jedem automatisch einen eigenen Worktree zu geben.

Methode 1: mündlich darum bitten. Schreib Claude im Gespräch:

Use worktrees for your agents.

Claude wendet die Isolation auf alle nachfolgenden Subagents in dieser Sitzung an.

Methode 2: direkt im Subagent festlegen. Füge in der Subagent-Datei (zum Beispiel .claude/agents/code-reviewer.md) dem Frontmatter ein Feld hinzu:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

You're a meticulous reviewer. Read the diff and look for logic errors...

Nun erhält jeder Start dieses Subagents einen temporären Worktree unter .claude/worktrees/. Wenn der Subagent nichts geschrieben hat, wird der Ordner automatisch gelöscht, sobald er fertig ist. Falls es nicht committete Änderungen gibt, fragt Claude, ob sie behalten oder entfernt werden sollen.

Der Basis-Branch für Subagent-Worktrees ist derselbe wie bei --worktree: standardmäßig origin/HEAD; mit worktree.baseRef: head das lokale HEAD.

Entscheidungsmatrix: Worktree, /bg, Subagent oder Agent View#

Typische Kombinationen:

• „2 Features manuell parallel“ – zwei Terminals, in jedem läuft claude --worktree. Der einfachste Fall.
• „Starte über Nacht ein Refactoring; ich schließe die App“ – /bg + /goal mit einer Abschlussbedingung. Die Sitzung läuft unabhängig von deinem Fenster.
• „Ein Prompt, drei parallele Untersuchungen“ – drei Subagents mit isolation: worktree. Jeder in seiner eigenen Sandbox.
• „Was läuft gerade?“ – claude agents. Ein Dashboard für alle Sitzungen mit den Filtern „running“, „blocked“ und „done“.

5 Stolperfallen bei der Arbeit mit Worktrees#

1. Worktree gestartet, .env fehlt, nichts funktioniert. Das häufigste Problem. Ein Worktree ist ein frischer Checkout ohne von Git ignorierte Dateien. Sobald du den Worktree-Modus einrichtest, solltest du eine .worktreeinclude-Datei mit .env* und den erforderlichen lokalen Konfigurationen hinzufügen. Prüfe, ob die Datei im Repository-Stammverzeichnis liegt, nicht unter .claude/.

2. Du möchtest zum Main-Branch wechseln, gehst mit cd zum Stammverzeichnis und verlierst deine nicht committeten Änderungen im Worktree. Der Stammordner und der Worktree sind zwei verschiedene Arbeitskopien. Du bist mit cd zurückgegangen; die Änderungen im Worktree sind dort geblieben – sie sind nicht verschwunden. Wenn du aber durcheinandergekommen bist und git stash im Hauptordner ausgeführt hast, weil du dachtest, du wärst im Worktree, wird der Stash auf dem Main-Branch erstellt, nicht auf dem erwarteten.

3. Fünf parallele Sitzungen gestartet und vergessen, was jede einzelne tut. Anthropics Dokumentation warnt ausdrücklich, dass die meisten Entwickler kognitiv nicht mehr als 2–3 Sitzungen bewältigen können. Ein Zeichen für Überlastung ist, Agent View zu öffnen und nicht sofort sagen zu können, was jeder Agent gerade tut. Beschränke dich auf zwei gleichzeitige Sitzungen. Wenn die Aufgabe mehr erfordert, sollte sie über /goal + Subagents orchestriert werden, nicht manuell.

4. Worktrees aus -p (Headless-Modus) werden nicht automatisch aufgeräumt. Der Befehl claude --worktree feature-x -p "do thing" zeigt keine interaktive Beendigungsabfrage an; Claude fragt also auch nicht „Worktree entfernen?“. Diese Worktrees sammeln sich an. Räume sie manuell auf: git worktree remove .claude/worktrees/feature-x. Oder verwende ein Cron-Skript, das alles entfernt, was älter als 7 Tage ist.

5. Vertrauensdialog in einem neuen Ordner. Wenn du das Repository zum ersten Mal öffnest und sofort claude --worktree ausführst, schlägt der Befehl fehl. Führe claude ohne Flags aus, bestätige das Vertrauen in den Arbeitsbereich und beende Claude – danach funktioniert --worktree. Das ist beabsichtigt, damit Claude nicht ohne Zustimmung des Benutzers auf das Projekt eines anderen zugreifen kann.

Aufräumen: Was automatisch gelöscht wird#

Die Aufräumlogik hängt davon ab, was du im Worktree gemacht hast und wie du die Sitzung gestartet hast. Anthropics Dokumentation listet drei Szenarien auf:

Szenario 1: Du hast den Worktree geöffnet, nichts getan und ihn wieder verlassen – der Worktree wurde entfernt.

Szenario 2: Du hast etwas bearbeitet, aber nichts committet – beim Beenden fragt Claude „behalten oder entfernen?“. Mit „Behalten“ bleiben der Ordner und der Branch für später erhalten. „Entfernen“ löscht das Verzeichnis zusammen mit nicht committeten Änderungen und neuen Commits. Das ist destruktiv – klicke nicht aus Gewohnheit auf „Entfernen“.

Szenario 3: Du hast mit -p (Headless-Modus) gestartet und der Befehl wurde beendet. Der Worktree bleibt bestehen. Räume ihn manuell auf:

git worktree remove .claude/worktrees/feature-x

Zusätzlich werden Worktrees aus Subagents und /bg-Sitzungen durch die Hintergrundbereinigung automatisch entfernt, wenn sie älter als cleanupPeriodDays Tage sind (eine Einstellung, normalerweise standardmäßig 30 Tage) und keine ungespeicherte Arbeit enthalten. Worktrees aus --worktree werden von der automatischen Bereinigung nicht angerührt – dafür bist du selbst verantwortlich.

Alternativen für SVN, Perforce und Mercurial: der Hook WorktreeCreate#

Wenn das Repository Subversion oder Mercurial verwendet, funktioniert das Flag --worktree nicht direkt. Anthropic bietet mit zwei Hooks eine Erweiterungsmöglichkeit: WorktreeCreate (erstellt eine isolierte Kopie) und WorktreeRemove (entfernt sie).

Beispiel eines SVN-Hooks aus der offiziellen Dokumentation:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Der Hook liest den Worktree-Namen von stdin ({ "name": "feature-auth" }), führt svn checkout in einem vorab festgelegten Verzeichnis aus und gibt den Pfad über stdout aus – Claude Code verwendet ihn als Arbeitsverzeichnis für die neue Sitzung.

Ein wichtiger Hinweis: Wenn du einen eigenen Hook verwendest, wird .worktreeinclude nicht eingesetzt. Wenn du .env oder andere von Git ignorierte Dateien im neuen Ordner brauchst, kopiere sie im Hook-Skript selbst.

Wie es weitergeht: drei verwandte Parallelisierungsmechanismen#

Worktree bietet Dateisystemisolation. /bg bietet Kontextisolation. Subagents bieten Aufgabenisolation. Jeder Mechanismus löst für sich ein einzelnes Problem. Zusammen ermöglichen sie es, drei bis fünf parallele Aufgaben ohne kognitiven Zusammenbruch zu bearbeiten. Das sind die Fähigkeiten, die hinter fortgeschrittenem Vibe-Coding im Jahr 2026 stehen.

Das Thema führt natürlich zu drei verwandten Themen: wie du mit /goal und Agent View einen autonomen Agent einrichtest, wie du eigene Subagents für deine Aufgaben erstellst und wie du über Dynamic Workflows Hunderte Agents startest.

Ailoot öffnen.