Claude Code Worktrees: Parallele Sitzungen ohne Konflikte
Ein Befehl gibt jeder Claude-Code-Sitzung eine eigene vollständige Kopie Ihres Repos. Lernen Sie claude --worktree kennen, das .claude/worktrees-Layout, Worktree-Isolation für Subagenten, das Aufräumen beim Beenden — und wo manuelles git worktree add noch gewinnt.
Kurz zusammengefasst
- claude --worktree (Kurzform -w) startet Ihre Sitzung in einer frischen Kopie des Repos unter .claude/worktrees/<name>, ausgecheckt auf einem Branch namens worktree-<name>.
- Starten Sie weitere Sitzungen in anderen Terminals, um parallel zu arbeiten — jede Sitzung bearbeitet ihr eigenes Verzeichnis und teilt sich dieselbe Git-History und dasselbe Remote.
- Auch Subagenten bekommen Worktrees: Fragen Sie in natürlicher Sprache oder setzen Sie isolation: worktree im Frontmatter einer .claude/agents/*.md, um es dauerhaft zu machen.
- Beim Beenden werden saubere unbenannte Worktrees automatisch entfernt, und laufende Arbeit fragt per Prompt nach Behalten oder Entfernen; Ergebnisse führen Sie mit einem normalen git merge von worktree-<name> zusammen.
Claude Code Worktrees in 7 Minutes
Kanal: Developers Digest7:10
I'm using claude --worktree for everything now
Kanal: Matt Pocock7:57
Worktrees — official documentation
Offizielle Doku: code.claude.com/docs
Jedes Flag, jeder Pfad und jedes Aufräum-Verhalten auf dieser Seite wurde gegen die offizielle Worktrees-Dokumentation geprüft; die Videos oben sind die visuelle und faktische Quelle — inklusive des Behalten/Entfernen-Prompts beim Beenden und der Push-nach-main-Falle.
Screenshots werden ihren Urhebern zugeordnet, mit Deep-Links zu den exakten Zeitstempeln. Keine Kamera-Bilder von Gesichtern.
Claude-Code-Worktrees Schritt für Schritt
Teil 1 — Ihre erste isolierte Sitzung
- 1
Ein Git-Repo mit mindestens einem Commit vorbereiten
Worktrees verzweigen von existierender History, darum braucht das Worktree-Feature ein echtes Git-Repository. Führen Sie in einem frischen Ordner git init aus, erstellen Sie eine Datei (die Demo führt nur touch index.html aus) und committen Sie. Ohne das hat Claude Code nichts, wovon es verzweigen könnte.
git init plus touch index.html — ein Commit ist alles, was das Worktree-Feature braucht, bevor claude --worktree läuft.Ansehen bei 1:06 - 2
Wissen, was ein Worktree eigentlich ist
Ein Git-Worktree ist ein zweites Arbeitsverzeichnis mit eigenen ausgecheckten Dateien und eigenem Branch, das History und Remote des Repositories teilt. Anders als beim Branch-Wechsel wird nichts gestasht: Haupt-Checkout und jeder Worktree bleiben gleichzeitig benutzbar — genau das, was parallele Agenten brauchen.
Ein Repository, viele Arbeitsordner: ../main, ../feature1 und ../feature2 sitzen gleichzeitig jeweils auf ihrem eigenen Branch.Ansehen bei 0:30 - 3
Claude Code mit --worktree starten
Führen Sie im Repo claude --worktree aus (oder die Kurzform claude -w). Claude Code erzeugt .claude/worktrees/<name>, generiert einen Namen wie bright-tumbling-rabbit, wenn Sie keinen angeben, und wirft die Sitzung direkt in diese Kopie. In der Desktop-App wählen Sie beim Start einer Sitzung stattdessen die Worktree-Option.
Der Willkommens-Banner zeigt: Das Arbeitsverzeichnis der Sitzung liegt bereits unter .claude/worktrees — alles Weitere passiert in der Kopie.Ansehen bei 1:22 - 4
Eine zweite Sitzung für die zweite Aufgabe öffnen
Führen Sie claude --worktree in einem weiteren Terminal erneut aus. Ohne Namen bekommen Sie einen weiteren unabhängigen Worktree; derselbe Name zweimal öffnet denselben wieder. Zwei Agenten können jetzt gleichzeitig am selben Projekt arbeiten, weil jeder nur sein eigenes Verzeichnis sieht.
Teil 2 — Wo Dateien und Befehle leben
- 5
Die vollständige Kopie unter .claude/worktrees ansehen
Öffnen Sie den Ordner im Dateimanager: Jeder Worktree ist ein vollständiger Checkout mit eigenem index.html, eigener .claude/settings.local.json und eigener git-Datei, während die schwere Objektdatenbank geteilt in der Haupt-.git bleibt. Deshalb ist eine weitere Kopie fast gratis.
Zwei Worktrees auf der Platte — clever-munching-toast und spicy-napping-otter — jeweils eine vollständige Projektkopie mit eigenem git-Ordner und index.html.Ansehen bei 1:50 - 6
Bestätigen, dass Befehle im Worktree bleiben
Wenn die erste Sitzung ihre Seite im Browser öffnet, zeigt der Permission-Prompt, dass der Pfad nach .claude/worktrees/clever-munching-toast zeigt — nicht in Ihren Haupt-Checkout. Claude Code blockiert außerdem, dass Subagenten den Haupt-Checkout direkt bearbeiten, und eine dieser Isolationsprüfungen lässt sich nicht abschalten.
Der Genehmigungsdialog nennt den exakten Worktree-Pfad — der Beweis, dass Sitzung eins nur ihre eigene Kopie des Projekts anfasst.Ansehen bei 1:42 - 7
Worktrees benennen oder aus PRs verzweigen (optional)
claude --worktree feature-auth erzeugt einen vorhersagbar benannten Worktree, und derselbe Name erneut öffnet ihn wieder, statt ein Duplikat zu erzeugen. Sie können auch eine quotierte PR-Nummer übergeben (claude --worktree "#1234") oder eine GitHub-/GitLab-PR-URL, um einen Worktree dieses Pull Requests unter .claude/worktrees/pr-<number> zu bekommen.
Teil 3 — Parallele Subagenten und Aufräumen
- 8
Parallele Subagenten mit Worktree-Isolation anfordern
Isolation skaliert über Terminals hinaus. Ein Prompt — „Starte fünf verschiedene Subagenten für fünf Varianten und nutze dabei die git-worktree-Isolation“ — lässt Claude Code Task-Agenten erzeugen, jeden in seinem eigenen isolierten Worktree, alle gleichzeitig am selben Repo ohne Kollisionen.
Fünf Task-Agenten starten parallel — jeder wird als in seinem eigenen isolierten git worktree arbeitend angekündigt.Ansehen bei 2:42 - 9
Zusehen, wie jeder Agent in seiner eigenen Spur läuft
Die Task-Liste zeigt alle fünf Varianten mit Tool-Nutzung und Token-Zählern, sodass Sie den Fortschritt sehen, ohne fünf Terminals zu öffnen. Subagent-Transkripte bleiben außerhalb des Kontexts des Haupt-Threads, was die steuernde Sitzung klein hält, während die Agenten die Schwerarbeit leisten.
Alle fünf Subagenten mitten im Lauf — Variation 1 schon fertig bei 50,3k Token, während die anderen Dateien in ihren eigenen Worktrees lesen.Ansehen bei 3:42 - 10
Varianten vergleichen, dann den Gewinner mergen
Wenn die Agenten fertig sind, listet Claude Code jede Variante mit ihrem Pfad unter .claude/worktrees/agent-<id>/ auf, sodass Sie sie nebeneinander im Browser öffnen können. Shippen Sie Ihre Lieblingsvariante mit einem normalen git merge ihres Worktree-Branchs (oder per PR) — Konflikte, falls welche auftreten, lösen sich wie bei jedem anderen Git-Merge.
Die Zusammenfassung nennt jede Variante mit ihrem .claude/worktrees-Pfad, daneben ist ein gerendertes Ergebnis geöffnet.Ansehen bei 4:22 - 11
Isolation als wiederverwendbaren Subagenten sichern
Um Worktree-Isolation dauerhaft zu machen, fragen Sie einfach: „Erstelle einen Front-end-Developer-Subagenten mit dem Haiku-Modell, der Worktree-Isolation nutzt.“ Claude Code recherchiert seine eigene Agent-Dokumentation und schreibt Ihnen eine neue Datei unter .claude/agents/.
Natürliche Sprache genügt — Claude Code prüft vor dem Schreiben der Datei seine eigene Doku zum Custom-Agent-Format.Ansehen bei 5:42 - 12
Das isolation: worktree im Frontmatter prüfen
Die erzeugte frontend-dev.md trägt name, description, model: haiku, eine Tools-Whitelist und — die neue Zeile — isolation: worktree. Jeder künftige Lauf dieses Subagenten passiert jetzt in einem temporären Worktree, der automatisch entfernt wird, wenn er ohne Änderungen abschließt.
Zeile 8 des Frontmatters — isolation: worktree — gibt jedem Lauf dieses Subagenten seinen eigenen Worktree.Ansehen bei 6:42 - 13
Mergen und Claude aufräumen lassen
Wenn Sie eine Sitzung beenden, prüft Claude Code den Worktree: Saubere unbenannte Worktrees werden automatisch entfernt, und bei allem mit Arbeit fragt er nach Behalten oder Entfernen — Behalten gibt den Befehl claude --worktree <name> --resume für später aus. Headless -p-Läufe räumen nie auf; die entfernen Sie mit git worktree remove.
Claude-Code-Worktrees vs. manuelles git worktree add
Worktrees gehören seit Jahren zu Git — neu ist, dass Claude Code ihren kompletten Lebenszyklus verwaltet. Die Unterschiede, die zählen:
- 1Erstellung: Von Hand führen Sie git worktree add ../project-feature -b feature aus, wechseln hinein und starten dann Claude. Mit claude --worktree landet die Sitzung in einem Schritt unter .claude/worktrees/<name> — von Ihnen benannt oder automatisch.
- 2Basis-Commit: worktree.baseRef steuert den Startpunkt — fresh (Standard) verzweigt vom Remote-Default-Branch, head nimmt Ihre noch nicht gepushten lokalen Commits mit. Das Flag kann keinen bestimmten Branch anzielen; dafür empfiehlt die Doku manuelles git worktree add.
- 3Dotfiles: Eine .worktreeinclude-Datei im Projektstamm kopiert gitignorierte Dateien wie .env in jeden neuen Worktree. Handgemachte Worktrees bekommen das nicht.
- 4Aufräumen: Claude Code prüft einen Worktree beim Beenden, entfernt saubere unbenannte automatisch, fragt vor laufender Arbeit nach und fegt verlassene Subagent-Worktrees regelmäßig zusammen. Manuelle Worktrees sind komplett Ihre Verantwortung.
- 5Schutzgeländer: Isolationsprüfungen hindern Subagenten daran, den Haupt-Checkout zu bearbeiten, und beim Fortsetzen einer Sitzung landen Sie zurück in ihrem Worktree. Plain git worktree add hat kein vergleichbares Sicherheitsnetz.
Darunter ist es trotzdem normales Git. VS Codes Source-Control-Panel listet jeden Worktree mit seinen Änderungen, Merges sind normale git-Merges, und handgemachte wie Claude-erzeugte Worktrees koexistieren im selben Repository — wählen Sie das Werkzeug pro Aufgabe.
Wenn ein Worktree nicht das tut, was er soll
Die meisten Stolperfallen sind Git-Grundlagen, die durchscheinen, keine Bugs im Feature. Diese fünf decken fast jede raue Kante ab:
- 1Der Push landet auf main. Ein frischer Worktree-Branch trackt den origin-Default-Branch, daher kann ein nacktes git push main treffen. Pushen Sie explizit mit git push origin worktree-<name> und halten Sie main geschützt.
- 2Dateien oder Tools fehlen. Gitignorierte Dateien (.env, vendor-Ordner) und repo-lokale Filter-Treiber wie LFS wandern nicht in einen neuen Worktree. Listen Sie sie in .worktreeinclude auf — oder führen Sie git lfs pull und Ihre Setup-Befehle im Worktree aus.
- 3Start schlägt mit einem Trust-Fehler fehl. In einem nicht vertrauenswürdigen Verzeichnis beendet sich claude --worktree mit einem Fehler, der Sie bittet, den Workspace zuerst zu akzeptieren — genehmigen und neu starten. (Nicht-interaktive -p-Läufe überspringen die Prüfung.)
- 4Zwei Worktrees kollidieren beim Merge. Wenn beide Aufgaben dieselbe Datei anfassen — Routes, eine Sidebar, package.json — lösen Sie beim Mergen Konflikte auf wie in jedem Git-Workflow. Worktrees beseitigen Kollisionen während des Laufs, nicht überschneidende Absichten.
- 5Übrig gebliebene Worktrees nach Headless-Läufen. -p-Läufe räumen nie hinter sich auf; löschen Sie sie manuell mit git worktree remove (führen Sie vorher git worktree unlock aus, falls einer gesperrt ist).
Einen Worktree unter einer laufenden Sitzung zu löschen ist auch nicht fatal: Beim nächsten Resume fällt er auf das Startverzeichnis zurück und die Bindung wird geleert. Sonst bricht nichts in der Sitzung.