Skip to main content
Ein Git-Worktree ist ein separates Arbeitsverzeichnis mit eigenen Dateien und Branch, das die gleiche Repository-Historie und Remote wie Ihr Haupt-Checkout teilt. Wenn Sie jede Claude Code-Sitzung in ihrem eigenen Worktree ausführen, erhält sie eine separate Kopie der Dateien zum Bearbeiten, sodass eine Sitzung ein Feature entwickeln kann, während eine zweite einen Bug behebt.
Worktrees erfordern ein Git-Repository; für andere Versionskontrollsysteme konfigurieren Sie Hooks, um die Git-Logik zu ersetzen. In der Desktop-App wählen Sie die Option worktree aus, wenn Sie eine Sitzung starten, um ihr ihren eigenen Worktree zu geben.
Worktrees sind eine von mehreren Möglichkeiten, Claude parallel auszuführen. Sie isolieren Datei-Änderungen. Subagents teilen die Arbeit innerhalb einer Sitzung auf, und sitzungsübergreifendes Messaging ermöglicht es Claude, Erkenntnisse zwischen den Sitzungen in Ihren Worktrees weiterzugeben. Siehe Agenten parallel ausführen, um die Ansätze zu vergleichen, oder springen Sie direkt zu Subagents mit Worktrees isolieren, um Worktrees und Subagents zusammen zu verwenden. Die meisten Sitzungen benötigen nur die ersten zwei Abschnitte: Starten Sie Claude in einem Worktree, dann bereinigen Sie, wenn Sie beenden. Kehren Sie zum Rest der Seite zurück, wenn Sie eine Sitzung fortsetzen, ändern, wie Worktrees erstellt werden, oder einen Fehler beheben müssen.

​
Starten Sie Claude in einem Worktree

Übergeben Sie --worktree oder -w mit einem Namen, um einen isolierten Worktree zu erstellen und Claude darin zu starten. Standardmäßig wird der Worktree unter .claude/worktrees/<name>/ in Ihrem Repository-Root erstellt, auf einem neuen Branch namens worktree-<name>:
Führen Sie den Befehl erneut mit einem anderen Namen in einem anderen Terminal aus, um eine zweite isolierte Sitzung zu starten. Wenn Sie den Namen weglassen, generiert Claude einen Namen wie bright-running-fox. Interaktive Ausführungen erfordern Workspace-Vertrauen: Wenn Sie Claude in dem Verzeichnis noch nicht ausgeführt haben, führen Sie claude einmal dort aus, um den Vertrauensdialog zu akzeptieren, oder --worktree beendet sich mit einem Fehler, der Sie dazu auffordert. Nicht-interaktive Ausführungen mit -p überspringen die Vertrauensprüfung, sodass claude -p --worktree ohne diese fortfährt.
Fügen Sie .claude/worktrees/ zu Ihrer .gitignore hinzu, damit Worktree-Inhalte nicht als nicht verfolgte Dateien in Ihrem Haupt-Checkout angezeigt werden.

​
Richten Sie die Worktree-Umgebung ein

Ein Worktree ist ein frischer Checkout, daher initialisieren Sie Ihre Entwicklungsumgebung dort: Bitten Sie Claude, Abhängigkeiten zu installieren, oder führen Sie die Einrichtung Ihres Projekts selbst im Worktree-Verzeichnis unter .claude/worktrees/ durch. Um gitignorierte Dateien wie .env automatisch in jeden neuen Worktree zu tragen, fügen Sie eine .worktreeinclude-Datei hinzu.

​
Bitten Sie Claude, einen Worktree zu erstellen

Sie können Claude auch während einer Sitzung bitten, „in einem Worktree zu arbeiten“, und es erstellt einen mit dem EnterWorktree-Tool. Sobald Sie sich in einem Worktree befinden, kann Claude direkt zu einem anderen unter .claude/worktrees/ wechseln, indem er EnterWorktree mit dem Zielpfad aufruft; der vorherige Worktree bleibt unverändert auf der Festplatte. Wenn Claude einen Pfad außerhalb des Verzeichnisses .claude/worktrees/ des Repositories betritt, fragt Claude Code zunächst nach Ihrer Genehmigung, da der Wechsel das Arbeitsverzeichnis der Sitzung, den Schreibzugriff und die Projektkonfiguration wie CLAUDE.md und Einstellungen an diesen Ort verschiebt. Eine EnterWorktree-Berechtigung oder die Wahl von „nicht mehr fragen“ unterdrückt diese Aufforderung nicht; nur der bypassPermissions-Modus überspringt sie. Vor v2.1.206 konnte Claude jeden vorhandenen Worktree-Pfad ohne Nachfrage betreten.
Hook-Pfade folgen dem Worktree nicht. Nachdem Claude einen Worktree betritt, behält Claude Code ${CLAUDE_PROJECT_DIR} in Ihren Hooks dort, wo er war, und übergibt den Worktree-Pfad auf andere Weise:
  • ${CLAUDE_PROJECT_DIR} bleibt an Ort und Stelle: Es zeigt immer noch auf das Projekt-Root, wo die Sitzung gestartet wurde, sodass ein Hook-Befehl wie ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh das Skript immer noch im Haupt-Checkout ausführt.
  • cwd folgt Claude: Das Feld cwd in der Hook-Eingabe-JSON ist das Worktree-Root, und es bewegt sich erneut, wenn Claude cd ausführt. Lesen Sie es, wenn ein Hook den Worktree-Pfad benötigt.

​
Worktrees bereinigen

Wenn Sie eine interaktive Worktree-Sitzung beenden, prüft Claude den Worktree auf Arbeiten, deren Entfernung gelöscht würde: geänderte oder nicht verfolgte Dateien, nicht committete Arbeiten in ausgecheckten Submodulen und neue Commits. Diese Regeln gelten für Worktrees, die Claude mit git erstellt hat. Für einen Worktree, den Ihr WorktreeCreate Hook erstellt hat, siehe stattdessen WorktreeRemove.
  • Der Worktree ist sauber: Bei einer unbenannten Sitzung entfernt Claude den Worktree und seinen Branch automatisch. Eine benannte Sitzung fragt Sie zuerst, damit Sie den Worktree später behalten können
  • Der Worktree enthält Arbeiten: Claude fragt Sie, ob Sie den Worktree behalten oder entfernen möchten. Das Behalten bewahrt das Verzeichnis und den Branch. Um später zurückzukehren, führen Sie den Befehl claude --worktree <name> --resume aus, den Claude Code beim Beenden ausgibt. Das Entfernen löscht das Worktree-Verzeichnis und seinen Branch zusammen mit allen darin enthaltenen Arbeiten
  • Der Zustand des Worktree kann nicht überprüft werden: Wenn Claude Code die Änderungen des Worktree nicht zählen kann oder seine Submodul-Checkouts nicht überprüfen kann, fragt es Sie, anstatt den Worktree automatisch zu entfernen. Die Eingabeaufforderung benennt, was nicht überprüft werden konnte
Nicht-interaktive Ausführungen mit -p haben keine Exit-Eingabeaufforderung, daher bereinigt Claude ihre Worktrees nicht, und Claude Code behält die Sperre, die es bei der Erstellung auf jedem einzelnen genommen hat, bis eine spätere Sitzung’s stale-lock sweep sie freigegeben hat. Um einen zu entfernen, führen Sie git worktree remove aus; wenn git sich weigert, weil der Worktree gesperrt ist, führen Sie zuerst git worktree unlock darauf aus. Unter Windows löscht das Entfernen eines Worktree keine Dateien außerhalb davon. Wenn ein Ordner im Worktree ein Link zu anderswo ist, z. B. eine NTFS-Verknüpfung oder ein Verzeichnis-Symlink, löscht Claude Code nur den Link und behält den Ordner, auf den er verweist. Vor v2.1.205 konnte das Entfernen eines Worktree mit einem Link in einem Unterverzeichnis den Ordner löschen, auf den er verwies.

​
Setzen Sie eine Worktree-Sitzung fort

Wenn Sie eine Sitzung fortsetzen, die sich in einem Worktree befand, ohne ihn zu beenden, kehrt Claude Code die Sitzung zu diesem Worktree zurück. Dies gilt für interaktive Fortsetzungen, für --continue und --resume im nicht-interaktiven Modus mit -p, und für das Agent SDK. --continue wählt die zuletzt aufgezeichnete Sitzung aus dem Verzeichnis aus, von dem Sie starten. Zurück im Worktree kann Claude ihn immer noch mit dem ExitWorktree-Tool verlassen. Bevor Claude Code die Sitzung zu ihrem Worktree zurückbringt, überprüft es, dass der Worktree immer noch ein separater Checkout vom Haupt-Checkout ist, und lehnt es ab, einen Worktree erneut zu betreten, der die Prüfung nicht besteht. Für einen Git-Worktree liest die Prüfung seine Git-Metadaten. Ein Worktree ohne Git-Metadaten, wie einer, den ein WorktreeCreate-Hook erstellt hat, kann die Prüfung bestehen; die Fälle, die Claude Code immer noch ablehnt, sind unter Claude Code weigert sich, einen Worktree zu verwenden mit ihren Wiederherstellungen aufgelistet. Für die Meldungen und wie Sie sich von jedem erholen, siehe Die Sitzung wird außerhalb ihres Worktrees fortgesetzt. Wo Sie starten und wie Sie fortsetzen, ändern, was Claude Code erneut betritt:
  • Startverzeichnis: Fortsetzen vom Haupt-Checkout oder einem anderen Verzeichnis des Repositories. Claude Code betritt einen Worktree, den es mit Git unter .claude/worktrees/ erstellt hat, auch wenn Sie von innen starten. Wenn Sie von innen in einem anderen Worktree starten, betritt Claude Code ihn nur, wenn es ihn von dort aus garantieren kann: ein Worktree, der sein eigenes Repository ist, einer ohne Git-Metadaten, oder ein Start aus einem Unterverzeichnis eines Worktrees, den Sie mit git worktree add erstellt haben, lehnt ab, daher starten Sie diese vom Haupt-Checkout.
  • --fork-session: Die abgespaltene Sitzung startet in dem Verzeichnis, von dem aus Sie Claude gestartet haben, und Claude Code hinterlässt den Worktree der ursprünglichen Sitzung unverändert.
  • Gelöschter Worktree: Wenn das Worktree-Verzeichnis nicht mehr existiert, setzt Claude Code die Sitzung in dem Verzeichnis fort, von dem aus Sie Claude gestartet haben. Es teilt Ihnen mit, dass der Worktree weg ist, und löscht die Worktree-Bindung der Sitzung.
Vor v2.1.212 blieb eine nicht-interaktive Fortsetzung im Startverzeichnis und ExitWorktree meldete, dass es keine aktive Worktree-Sitzung zum Beenden gab.
Wenn Claude einen Worktree betritt oder verlässt, den Claude Code mit Git erstellt hat, folgt das Transkript: Claude Code zeichnet die Sitzung unter dem neuen Arbeitsverzeichnis der Sitzung auf, auf die gleiche Weise wie /cd, sodass /desktop und --resume sie dort finden. Das Verlassen verschiebt es auf die gleiche Weise zurück. Ein Worktree, der von einem WorktreeCreate-Hook erstellt wurde, behält sein Transkript im Startverzeichnis. Erfordert Claude Code v2.1.198 oder später.

​
Wie Claude Code Isolation erzwingt

Während eine Sitzung in einem Worktree isoliert ist, blockiert Claude Code die Tool-Aufrufe, die die folgenden Prüfungen definieren. Die gleichen Regeln gelten, ob Sie die Sitzung mit --worktree gestartet haben, Claude einen Worktree mit EnterWorktree betritt, oder Sie eine Worktree-Sitzung fortsetzen. Die gleiche Erzwingung gilt für jeden Subagent, den Claude aus der isolierten Sitzung erzeugt. Sie gilt, ob die Sitzung interaktiv ist oder im Hintergrund läuft. Subagents, die in ihrem eigenen Worktree laufen, tragen die gleichen Prüfungen. Ihre Versionsverlauf ist unter Schreiben Sie Subagent-Dateien. Claude Code wendet vier Prüfungen an:
  • Datei-Änderungen: Claude Code blockiert einen Edit, Write oder NotebookEdit, der auf einen Pfad im Haupt-Checkout abzielt.
  • Befehl-Arbeitsverzeichnis: Claude Code blockiert einen Bash-, PowerShell- oder Monitor-Befehl, dessen Arbeitsverzeichnis zum Haupt-Checkout aufgelöst wird, oder dessen Arbeitsverzeichnis es nicht überprüfen kann, dass es außerhalb bleibt.
  • Git-Umleitungen: Claude Code blockiert einen Bash- oder Monitor-Befehl, der Git in den Haupt-Checkout umleitet. Die Umleitung kann durch git -C, --git-dir, eine GIT_DIR- oder GIT_WORK_TREE-Variable oder ein cd in den Haupt-Checkout vor dem Ausführen von Git erfolgen.
  • Befehlsform: Claude Code blockiert einen Bash- oder Monitor-Befehl, wenn es nicht überprüfen kann, dass jedes Git, das der Befehl ausführt, im Worktree bleibt. Das geschieht beispielsweise, wenn der Befehlsname zur Laufzeit berechnet wird, wenn die Syntax nicht analysiert werden kann, oder wenn eine Erweiterung wie ${!name} oder ${ command; } einen Befehl ausführen könnte, den der Text nicht ausdrücklich angibt. Claude Code teilt Claude mit, wie der abgelehnte Befehl umgeschrieben werden kann, z. B. durch Aufteilen in einfache, separate Befehle. Sie können diese Prüfung nicht ausschalten.
Diese Prüfungen lesen den Pfad, auf den eine Änderung abzielt, das Verzeichnis, in dem ein Befehl ausgeführt wird, und den Text des Befehls. Keine von ihnen verfolgt, welche Dateien ein Shell-Befehl schreibt. Ein Befehl, der in den Haupt-Checkout schreibt, ohne dort Git auszuführen, wie cp oder eine Shell-Umleitung, wird daher von ihnen nicht abgelehnt. Claude Code behandelt diesen Befehl wie jeden anderen Shell-Befehl gemäß Ihren Einstellungen für Berechtigungen und Sandboxing. Die Prüfungen gelten für das Repository, von dem aus Sie Claude Code gestartet haben. Sie decken auch den Haupt-Checkout ab, von dem ein verknüpfter Worktree verknüpft ist. Für PowerShell-Befehle wendet Claude Code nur die Arbeitsverzeichnis-Prüfung an. Claude sieht jede Ablehnung als einen Tool-Fehler, der den Worktree benennt und sagt, wie man fortfährt. Für einen abgelehnten Befehl siehe was die Ablehnungsmeldung bedeutet und wie man sie löscht.

​
Isolieren Sie Subagents mit Worktrees

Subagents können in ihren eigenen Worktrees laufen, sodass parallele Änderungen nicht kollidieren. Bitten Sie Claude, „Worktrees für Ihre Agenten zu verwenden“, oder machen Sie die Isolation dauerhaft für einen benutzerdefinierten Subagent, indem Sie isolation: worktree zu seinem Frontmatter hinzufügen. Dieser Subagent in .claude/agents/ läuft immer in seinem eigenen Worktree:
Jeder Subagent erhält einen temporären Worktree, den Claude Code automatisch entfernt, wenn der Subagent ohne Änderungen beendet wird; ein Worktree mit Änderungen bleibt auf der Festplatte, bis die