Claude Code Worktrees: parallele Sitzungen ohne Kollisionen

Zwei Claude-Code-Sitzungen im selben Verzeichnis sind ein Rezept für Ärger: die eine baut ein Feature, die andere behebt einen Fehler, und beide schreiben in dieselben Dateien. Git-Worktrees lösen das seit Jahren für Menschen, und Claude Code hat den Weg eingebaut. Dieser Artikel erklärt, wie Sie eine Sitzung in einem Worktree starten, was dabei kopiert wird und was nicht, wie die Isolation durchgesetzt wird, wann aufgeräumt wird und wie Subagenten eigene Worktrees bekommen. Grundlage ist die Hersteller-Dokumentation, Stand September 2026.

Was ein Worktree ist

Ein Git-Worktree ist ein zweites Arbeitsverzeichnis desselben Repositories: eigene Dateien, eigener Branch, aber dieselbe Historie und derselbe Remote wie Ihr Haupt-Checkout. Was Sie in einem Worktree ändern, bleibt dort. Läuft jede Claude-Code-Sitzung in ihrem eigenen Worktree, kann eine Sitzung ein Feature bauen, während eine zweite einen Fehler behebt, ohne dass sich die beiden je in die Quere kommen.

Worktrees setzen ein Git-Repository mit mindestens einem Commit voraus. Für andere Versionsverwaltungen lässt sich die Git-Logik über Hooks ersetzen; dazu am Ende mehr. In der Desktop-App bekommt jede neue Sitzung automatisch einen eigenen Worktree.

Eine Sitzung im Worktree starten

claude --worktree feature-auth
# kurz:
claude -w feature-auth

Claude Code legt den Worktree unter .claude/worktrees/feature-auth/ im Repository an, auf einem neuen Branch worktree-feature-auth, und startet dort. Denselben Befehl mit einem anderen Namen in einem zweiten Terminal, und die zweite Sitzung läuft isoliert daneben. Lassen Sie den Namen weg, erzeugt Claude Code einen wie bright-running-fox.

Zwei Dinge vorab: Interaktive Sitzungen brauchen das Vertrauen in das Verzeichnis; haben Sie Claude dort noch nie gestartet, tun Sie das einmal ohne Flag und bestätigen den Dialog. Und tragen Sie .claude/worktrees/ in Ihre .gitignore ein, sonst erscheinen die Worktree-Inhalte im Haupt-Checkout als unversionierte Dateien.

Was im Worktree fehlt, und wie es hineinkommt

Ein Worktree ist ein frischer Checkout. Abhängigkeiten sind nicht installiert, und alles, was Git ignoriert, ist nicht da: .env, lokale Konfigurationen, Geheimnisse. Die Abhängigkeiten installieren Sie wie gewohnt, oder Sie bitten Claude darum. Für die ignorierten Dateien gibt es .worktreeinclude im Projektstamm, in .gitignore-Syntax:

# .worktreeinclude
.env
.env.local
config/secrets.json

Kopiert wird nur, was zu einem Muster passt und in Git ignoriert ist; versionierte Dateien werden nie verdoppelt. Das gilt für jeden Worktree, den Claude Code mit Git anlegt: über --worktree, für Subagenten und in der Desktop-App.

Claude selbst in einen Worktree schicken

Sie müssen die Sitzung nicht neu starten. „Arbeite in einem Worktree“ genügt, und Claude legt mit dem Werkzeug EnterWorktree einen an. Von dort kann Claude direkt in einen anderen Worktree unter .claude/worktrees/ wechseln; der vorherige bleibt unverändert liegen. Ein Pfad außerhalb dieses Verzeichnisses braucht Ihre Zustimmung, weil damit Arbeitsverzeichnis, Schreibrechte und Projektkonfiguration mitwandern.

Eine Falle für Hook-Nutzer: ${CLAUDE_PROJECT_DIR} zeigt weiter auf den Projektstamm, in dem die Sitzung begann. Den Worktree-Pfad bekommt ein Hook über das Feld cwd in seinen Eingabedaten.

Wie die Isolation durchgesetzt wird

Isolation ist bei Claude Code keine Empfehlung, sondern eine Sperre. Solange eine Sitzung in einem Worktree läuft, blockiert Claude Code vier Arten von Aufrufen, und zwar auch für jeden Subagenten, den diese Sitzung startet:

• Dateiänderungen per Edit, Write oder NotebookEdit an Pfaden im Haupt-Checkout
• Befehle, deren Arbeitsverzeichnis im Haupt-Checkout liegt oder sich nicht sicher außerhalb verorten lässt
• Git-Umleitungen in den Haupt-Checkout, etwa über git -C, --git-dir, GIT_DIR, GIT_WORK_TREE oder ein cd vor dem Git-Aufruf
• Befehlsformen, die sich ohne Ausführung nicht nachvollziehen lassen, etwa Klammer-Erweiterungen und Heredocs mit ungequoteten Begrenzern; diese Prüfung lässt sich nicht abschalten

Claude sieht jede Ablehnung als Werkzeugfehler, der den Worktree nennt und sagt, wie es weitergeht, etwa durch Aufteilen eines Befehls in einfache Einzelschritte.

Aufräumen beim Beenden

Beim Verlassen einer interaktiven Worktree-Sitzung prüft Claude Code, ob Arbeit verloren ginge: geänderte oder neue Dateien, neue Commits.

• Worktree sauber: bei einer unbenannten Sitzung wird er samt Branch entfernt; eine benannte Sitzung fragt vorher, damit Sie ihn behalten können.
• Worktree mit Arbeit: Claude Code fragt, ob behalten oder entfernen. Entfernen löscht Verzeichnis und Branch samt Inhalt.
• Nicht-interaktiv mit -p: kein Dialog, kein Aufräumen. Entfernen Sie mit git worktree remove, bei einer Sperre vorher git worktree unlock.

Nehmen Sie eine Sitzung später wieder auf, kehrt Claude Code in ihren Worktree zurück, auch bei --continue und --resume. Existiert das Verzeichnis nicht mehr, läuft die Sitzung dort weiter, wo Sie Claude gestartet haben, und die Bindung wird gelöscht.

Subagenten mit eigenem Worktree

Sollen mehrere Subagenten parallel Dateien ändern, bekommt jeder seinen eigenen Worktree. Entweder bitten Sie Claude darum („nutze Worktrees für die Agenten“), oder Sie machen es für einen eigenen Agenten dauerhaft:

---
name: umbauer
description: Führt mechanische Umbauten über viele Dateien durch
isolation: worktree
---

Führen Sie den gewünschten Umbau in jeder betroffenen Datei durch, lassen Sie
die Tests laufen und berichten Sie das Ergebnis.

Jeder Subagent erhält einen temporären Worktree. Endet er ohne Änderungen, wird der Worktree sofort entfernt; mit Änderungen bleibt er, bis eine regelmäßige Aufräumrunde ihn nach Ablauf von cleanupPeriodDays gefahrlos entfernen kann. Während der Agent läuft, hält Claude Code eine Sperre auf dem Worktree, damit keine parallele Aufräumrunde ihn wegnimmt. Wie Sie Subagenten anlegen und aufrufen, steht im Artikel zu Subagenten in Claude Code.

Basis-Branch, Pull-Requests, Wiederverwendung

Ein neuer Worktree zweigt standardmäßig vom Standard-Branch des Repositories auf dem Remote ab, meist main. Wer Subagenten auf laufende Arbeit ansetzen will, stellt in den Einstellungen um:

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

Die Einstellung kennt nur zwei Werte: fresh (Standard) und head; einen Branch-Namen nimmt sie nicht an, dafür gibt es den Handweg weiter unten. Mit "head" startet der Worktree von Ihrem aktuellen lokalen HEAD, samt nicht gepushter Commits. Einen bestimmten Pull-Request holen Sie sich mit der Nummer: claude --worktree "#1234" erzeugt den Worktree unter .claude/worktrees/pr-1234 aus dem Kopf des Pull-Requests; die Anführungszeichen verhindern, dass die Shell das Rautezeichen als Kommentar liest. Ein Name, dessen Verzeichnis schon existiert, öffnet den vorhandenen Worktree. Ist er sauber, noch auf seinem Branch und ohne eigene Commits, setzt Claude Code ihn dabei bei der Standardeinstellung fresh auf den Standard-Branch zurück.

Was Worktrees mit dem Haupt-Checkout teilen

• das .git-Verzeichnis des Repositories; git commit funktioniert im Worktree auch mit aktivierter Sandbox
• Plugins, die im Projekt installiert sind, ohne Neuinstallation je Worktree
• Berechtigungen: ein „Ja, nicht mehr fragen“ für einen Befehl im Worktree landet in der .claude/settings.local.json des Haupt-Checkouts und gilt in jedem Worktree des Repositories

Worktrees von Hand

Für einen bestehenden Branch oder einen Ort außerhalb des Repositories legen Sie den Worktree mit Git selbst an und starten Claude darin:

git worktree add ../projekt-feature-a -b feature-a
cd ../projekt-feature-a
claude

git worktree list
git worktree remove ../projekt-feature-a

Und ein Hinweis zur CLAUDE.md: eine per .gitignore ausgeschlossene CLAUDE.local.md existiert nur in dem Worktree, in dem Sie sie angelegt haben. Persönliche Anweisungen, die in jedem Worktree gelten sollen, importieren Sie aus dem Home-Verzeichnis, etwa mit @~/.claude/mein-projekt.md.

Andere Versionsverwaltungen

Für SVN, Perforce oder Mercurial ersetzen die Hooks WorktreeCreate und WorktreeRemove die Git-Logik: der Hook liest den Namen aus der Eingabe, legt ein Arbeitsverzeichnis an und gibt dessen Pfad aus. .worktreeinclude greift dann nicht; das Kopieren lokaler Dateien übernimmt der Hook selbst.

Fazit

Worktrees machen aus „eine Sitzung nach der anderen“ ein „mehrere Sitzungen nebeneinander“, ohne dass Sie sich Branch-Wechsel und halbfertige Dateien merken müssen. Der Einstieg ist ein Flag; das Aufräumen übernimmt Claude Code, solange Sie interaktiv arbeiten. Wer .worktreeinclude einmal gepflegt hat, muss im neuen Worktree nur noch die Abhängigkeiten installieren.

Weiterführend

• Claude Code Subagenten: Aufgaben delegieren, Kontext sauber halten
• CLAUDE.md erstellen und richtig aufbauen
• Claude Code Cheat Sheet