Claude Code Worktrees

Problem: Eine Claude Code-Session läuft auf einem Feature-Branch und ein Production-Bug landet auf deinem Tisch. Deine Optionen sind schlecht: stashen und den Working-State verlieren, ein zweites Terminal öffnen und zusehen, wie beide Sessions um dieselben Dateien kämpfen, oder die Session komplett abbrechen.

Schnelle Lösung: Öffne eine zweite Claude Code-Session in ihrem eigenen Worktree:

claude --worktree bugfix-123

Ein frisches Working-Directory landet in .claude/worktrees/bugfix-123/ auf seinem eigenen Branch worktree-bugfix-123. Die erste Session bleibt unberührt. Nichts wird gestasht. Nichts kollidiert. Zwei Claude-Sessions laufen nebeneinander, und keine weiß, dass die andere existiert.

Wenn du zwischen Agent-Mustern entscheidest, halte die Grenze einfach: lies Agent Fundamentals, wenn du Subagents, Slash-Commands oder leichtgewichtige Spezialisierung innerhalb einer Session brauchst. Lies diese Seite, wenn das echte Problem Dateisystem-Isolation, separate Branches und parallele Arbeit ist, die denselben Checkout nicht berühren darf. Für Orchestrierungsmuster auf dieser Isolation lies Agent Patterns.

Warum Worktrees alles verändern

Wer Claude Code mit Sub-Agents oder Background-Agents gepusht hat, kennt die Grenze. Zwei Agents fangen gleichzeitig an, dieselbe Datei zu bearbeiten. Einer schreibt src/auth.ts um, während der andere mitten im selben Modul steckt. Was zurückkommt, sind halb angewendete Änderungen, ein Merge-Chaos oder etwas Schlimmeres.

Worktrees beheben das auf Dateisystem-Ebene. Jeder ist ein separater Checkout des Repos mit eigenem Branch, eigenem Verzeichnis und eigenem Index. Worktree-Unterstützung wurde in Claude Code v2.1.50 zu einem First-Class-Feature, das das Erstellen, Verwalten und Aufräumen über die CLI, die Desktop-App und sogar Custom Agents abdeckt.

Die CLI: das --worktree-Flag

Claude Code mit dem --worktree-Flag zu starten ist der schnellste Weg rein.

Benannte Worktrees

# Claude in einem benannten Worktree starten
claude --worktree feature-auth
 
# Erstellt:
# .claude/worktrees/feature-auth/  (Working-Directory)
# Branch: worktree-feature-auth    (abgezweigt vom Standard-Remote-Branch)

Jeder Worktree landet in seinem eigenen Ordner unter .claude/worktrees/ auf einem dedizierten Branch. Erstelle so viele, wie deine Festplatte hergibt.

Automatisch benannte Worktrees

# Claude einen Namen generieren lassen
claude --worktree

Praktisch für Wegwerf-Runs, bei denen der Branch-Name wirklich keine Rolle spielt.

Mehrere parallele Sessions

# Terminal 1: an Auth arbeiten
claude --worktree feature-auth
 
# Terminal 2: einen Bug fixen
claude --worktree bugfix-123
 
# Terminal 3: ein Refactor erkunden
claude --worktree experiment-new-router

Drei Sessions. Drei Branches. Null Konflikte. Jede kann die gesamte Git-History lesen, aber die Dateien unter jeder Session leben in ihrem eigenen Tree.

Worktree mitten in einer Session erstellen

Das Flag ist beim Start nicht erforderlich. Du kannst es in jeder laufenden Session anfragen:

You: work in a worktree
Claude: I'll create an isolated worktree for this session...

Claude richtet den Worktree ein und bewegt die Session hinein. Das rettet dich, wenn sich mitten in einem Gespräch herausstellt, dass die Arbeit von Anfang an isoliert hätte sein sollen.

Desktop-App: Automatische Isolation

Die Claude Code Desktop-App geht einen Schritt weiter. Jede neue Session bekommt standardmäßig ihren eigenen Worktree.

Standardmäßig landen diese Worktrees in .claude/worktrees/. Desktop-Einstellungen lassen dich den Pfad ändern und ein Branch-Präfix setzen, damit Claude-erstellte Branches gruppiert bleiben. Session fertig? Klick auf das Archiv-Symbol und der Worktree samt Branch verschwindet.

Jede Desktop-Session ist also von Haus aus sicher. Sessions überschreiben sich nicht, und du musst sie nicht koordinieren.

Subagent-Worktree-Isolation

Hier zahlt sich das Feature aus. Jeder Sub-Agent, den Claude für eine verteilte Aufgabe spawnt, kann seinen eigenen Worktree bekommen.

Claude bitten, Agents zu isolieren

Einfachste Version:

You: Use worktrees for your agents when doing this refactor

Jeder Sub-Agent landet in seinem eigenen Worktree. Ein Worktree, der ohne Änderungen fertig wird, wird von selbst weggeworfen. Ein Worktree, der tatsächlich etwas geändert hat, bleibt für dich zur Überprüfung erhalten.

Warum das für parallele Ausführung wichtig ist

Ohne Isolation können parallele Sub-Agents nur Dateien lesen oder in nicht überlappenden Pfaden schreiben. Das ist eine schwache Grenze. Sobald ein Agent in die Spur eines anderen gerät, gibt es stille Konflikte.

Mit Isolation sieht jeder Agent die gesamte Codebasis für sich allein. Agent A kann src/auth.ts auf eine Art angehen, während Agent B dieselbe Datei auf eine andere Art angeht. Du öffnest beide Branches danach und nimmst den besseren (oder nähst Teile von beiden zusammen).

Das glänzt wirklich bei Batch-Migrationen. Du hast 50 Dateien von einer API auf eine andere zu verschieben? Starte fünf Agents, je zehn Dateien, jeden in seinem eigenen Worktree. Sie arbeiten parallel und niemand stolpert über jemanden. Der eingebaute /batch-Befehl fährt auf derselben Schiene und startet Worktree-isolierte Agents aus einem einzigen Prompt heraus, um Migrationen über eine Codebasis hinweg auszuführen.

Custom Agents mit eingebauter Isolation

Custom Agents unter .claude/agents/ können festgelegt werden, immer einen Worktree zu verwenden:

---
name: refactor-agent
description: Agent that performs isolated refactoring work
isolation: worktree
---
You are a refactoring specialist. Analyze the target code,
plan the refactor, and implement changes.

isolation: worktree im Frontmatter weist Claude an, bei jedem Start dieses Agents einen frischen Worktree zu erstellen. Der Agent arbeitet in vollständiger Isolation, und ein leerer Worktree löscht sich am Ende des Runs von selbst.

Unterstützung für Nicht-Git-VCS

Teams mit Mercurial, Perforce oder SVN sind nicht ausgesperrt. Der Worktree-Modus läuft trotzdem, mit Custom Hooks. Registriere WorktreeCreate- und WorktreeRemove-Hooks in deinen Einstellungen, damit die eigene Isolationslogik deines VCS das Standard-Git-Verhalten ersetzt.

Mit diesen Hooks werden das --worktree-Flag und In-Session-Worktree-Anfragen über deine Hooks geleitet statt git aufzurufen. Alles andere am Ablauf bleibt unverändert.

Drei Worktree-Muster, die du dir leihen solltest

Die meisten Teams verstehen die Grundidee, sobald sie sie sehen. Was sie meist als nächstes brauchen, ist ein funktionierendes Muster zum Kopieren.

1. Hotfix ohne die Feature-Arbeit zu sprengen

Du bist mitten in einem Feature-Branch, als ein Production-Auth-Bug landet.

# Deine aktuelle Feature-Session am Leben lassen
claude

# Eine zweite isolierte Bugfix-Session öffnen
claude --worktree hotfix-auth-timeout

Jetzt kann der Hotfix sauber ausgeliefert werden, während die Feature-Session ihren State, ihre Todos und ihre Conversation-History behält. Das ist die einfachste hochwertige Nutzung von Worktrees und die, die die meisten Teams zuerst adoptieren.

2. Konkurrierende Implementierungen für dasselbe riskante Refactor

Angenommen, ein Routing-Refactor hat zwei mögliche Formen. Eine behält die aktuelle API-Oberfläche und verschiebt Interna. Die andere vereinfacht auch die externe API.

Beide ausführen:

claude --worktree router-safe-path
claude --worktree router-clean-slate

Beide Sessions können dieselben Dateien anfassen, weil sie keinen Checkout teilen. Überprüfe beide Branches danach und behalte das stärkere Design. Das ist weit besser, als einen Agent zu zwingen, beide Pfade in einem einzigen Context durchzudenken.

3. Batch-Migrationen mit isolierten Subagents

Sagen wir, du musst eine Logging-API in 80 Dateien ersetzen. Du willst nicht fünf Agents auf demselben Checkout haben.

Fordere die Aufteilung explizit an:

You: Use worktrees for agents. Split this migration into 5 batches of files.

Das gibt jedem Worker:

• eine vollständige Repo-Sicht
• einen engen Datei-Batch
• einen isolierten Branch
• ein überprüfbares Ergebnis

Hier hören Worktrees auf, ein Komfort-Feature zu sein, und fangen an, sich wie echte parallele Infrastruktur zu verhalten.

Kleine Regeln, die Worktrees vernünftig halten

Die Mechanik ist einfach. Die Team-Gewohnheiten sind das, was sie nützlich hält:

• Worktrees nach dem Ergebnis benennen, nicht nur nach dem Ticket
• Leere oder aufgegebene Worktrees schnell löschen
• Einen Worktree pro aktivem Gedankengang verwenden
• Branch-Präfixe konsistent halten, damit das Aufräumen offensichtlich ist
• Diffs vor dem Mergen zwischen Worktrees reviewen wie jeden anderen Branch

Wenn Worktrees anfangen, unübersichtlich zu werden, liegt es normalerweise nicht daran, dass es zu viele gibt. Es liegt daran, dass niemand sagen kann, welche wegwerfbar sind und welche wichtig sind.

Cleanup und Housekeeping

Wie ein Worktree aufgeräumt wird, hängt davon ab, ob darin tatsächlich etwas geändert wurde:

• Keine Änderungen: Der Worktree und sein Branch werden automatisch entfernt, wenn die Session endet
• Änderungen vorhanden: Claude fragt dich, ob du den Worktree behalten oder entfernen möchtest

Worktree-Ordner aus der Versionskontrolle mit einer Zeile in .gitignore heraushalten:

echo ".claude/worktrees/" >> .gitignore

Worktrees stapeln sich? Normale Git-Befehle listen sie auf und bereinigen sie:

git worktree list
git worktree prune

Wann Worktrees einsetzen

Daumenregel: Immer wenn du nach einem separaten Branch greifen würdest, um Konflikten auszuweichen, greife stattdessen nach einem Worktree. Du bekommst den Branch, und ein separates Working-Directory dazu.

Merke: Worktrees verwandeln Claude Code von einem Thread in eine parallele Entwicklungsumgebung. Isolierte Sessions starten. Isolierte Agents entsenden. Die Gewinner zusammenführen, wenn du bereit bist.