Parallele Sitzungen mit Worktrees ausführen

​

Starten Sie Claude in einem Worktree

claude --worktree feature-auth

​

Richten Sie die Worktree-Umgebung ein

​

Bitten Sie Claude, einen Worktree zu erstellen

​

Bereinigen Sie Worktrees

• Der Worktree ist sauber: Für eine unbenannte Sitzung entfernt Claude den Worktree und seinen Branch automatisch. Eine benannte Sitzung fordert Sie zunächst auf, damit Sie den Worktree später behalten können
• Der Worktree enthält Arbeit: Claude fordert Sie auf, den Worktree zu behalten oder zu entfernen. Das Behalten bewahrt das Verzeichnis und den Branch, sodass Sie später zurückkehren können. Das Entfernen löscht das Worktree-Verzeichnis und seinen Branch zusammen mit der gesamten Arbeit darin
• Der Zustand des Worktrees kann nicht überprüft werden: Wenn Claude Code die Änderungen des Worktrees nicht zählen kann oder seine Submodul-Checkouts nicht überprüfen kann, fordert es Sie auf, anstatt den Worktree automatisch zu entfernen. Die Aufforderung benennt, was nicht überprüft werden konnte

​

Setzen Sie eine Worktree-Sitzung fort

• 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.

​

Wie Claude Code Isolation erzwingt

• 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.

​

Isolieren Sie Subagents mit Worktrees

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

​

Bereinigen Sie Subagent- und Hintergrund-Sitzungs-Worktrees

• Der Worktree hält immer noch Arbeit: geänderte oder nicht verfolgte Dateien oder nicht gepushte Commits.
• Ein ausgechecktes Submodul im Worktree hält geänderte oder nicht verfolgte Dateien, oder Claude Code kann die Submodule des Worktrees nicht inspizieren. Diese Überprüfung erfordert Claude Code v2.1.274 oder später.
• Einer der vier Fälle, die auch die Worktree-Erstellung blockieren trifft zu: Claude Code kann nicht bestimmen, welche Filter-Treiber die Repository-Konfiguration definiert, oder findet dort eine Einstellung, die es nicht ausschalten kann.
• Der Worktree gehört zu einer --worktree-Sitzung, die Sie nicht in den Hintergrund verschoben haben, unabhängig von seinem Alter.
• Sie haben den Worktree selbst mit git worktree add erstellt, auch wenn Sie dann eine --worktree <name>-Sitzung darin ausgeführt und diese Sitzung in den Hintergrund verschoben haben.

​

Passen Sie die Worktree-Erstellung an

​

Wählen Sie den Basis-Branch

• "fresh" (Standard): Verzweigung vom Standard-Branch des Repositories auf dem Remote, normalerweise main, sodass der Worktree von einem sauberen Tree startet, der dem Remote entspricht.
• "head": Verzweigung von Ihrem aktuellen lokalen HEAD, sodass der Worktree Ihre nicht gepushten Commits und Feature-Branch-Status trägt. Verwenden Sie dies, wenn Sie Subagents isolieren, die an laufenden Arbeiten arbeiten müssen. Innerhalb eines Worktrees wird "head" zu diesem Worktrees HEAD aufgelöst, nicht zum HEAD des Haupt-Checkouts.

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

​

Verzweigung von einem Pull Request

claude --worktree "#1234"

• github.com: ruft pull/<number>/head ab
• gitlab.com: ruft merge-requests/<number>/head ab
• GitHub Enterprise, selbstverwaltetes GitLab oder ein anderer Host: versucht zuerst pull/<number>/head, dann merge-requests/<number>/head

​

Kopieren Sie gitignorierte Dateien in Worktrees

.env
.env.local
config/secrets.json

​

Verwenden Sie einen Worktree-Namen erneut

• Es hat keine nicht committeten Änderungen oder nicht verfolgten Dateien.
• Es befindet sich immer noch auf dem Branch, den Claude Code für ihn erstellt hat.
• Es hat keine Commits von sich selbst, oder sein Pull Request oder Merge Request wurde zusammengeführt und sein Remote-Branch gelöscht.

• Der Worktree erfüllt eine der Bedingungen nicht.
• Claude Code kann den Status des Worktrees nicht überprüfen.
• worktree.baseRef ist "head".
• Der Name ist eine Pull-Request- oder Merge-Request-Referenz.

​

Ersetzen Sie die Worktree-Erstellung durch einen Hook

​

Was Worktrees mit dem Haupt-Checkout teilen

• Das .git-Verzeichnis des Repositories: Git-Befehle in einem Worktree schreiben in das gemeinsame .git-Verzeichnis des Haupt-Repositories, und Sandboxing erlaubt diese Schreibvorgänge, sodass Befehle wie git commit von innen in einem Worktree mit aktivierter Sandbox funktionieren.
• Plugins: Plugins, die im Projekt-Bereich aus dem Haupt-Checkout installiert sind, werden auch in Worktrees desselben Repositories geladen, sodass Sie sie nicht pro Worktree neu installieren müssen. Erfordert Claude Code v2.1.200 oder später.
• Genehmigungen: Das Wählen von „Ja, und nicht mehr fragen” für einen Bash-Befehl in einer Worktree-Sitzung speichert die Regel in der .claude/settings.local.json des Haupt-Checkouts, sodass sie im Haupt-Checkout und in jedem anderen Worktree des Repositories gilt und das Entfernen des Worktrees überlebt. Unter Windows und in den anderen Fällen, in denen Claude Code das Repository-Root nicht verwendet, bleibt die Regel bei diesem Worktree. Vor v2.1.211 wurde eine Genehmigung, die in einem Worktree gewährt wurde, in diesem Worktree gespeichert, galt nicht anderswo und ging verloren, wenn der Worktree entfernt wurde. Siehe wo Genehmigungen gespeichert werden.
• Nicht nachverfölgte Skills, Agents und Befehle: Wenn der Worktree-Checkout kein .claude/skills-Verzeichnis in seinem Root hat, zum Beispiel weil Ihr .claude/skills gitignoriert ist, lädt Claude Code die Projekt-Skills des Haupt-Checkouts in der Worktree-Sitzung. In einem Worktree mit seinem eigenen .claude/skills-Verzeichnis wird nur diese Kopie geladen. Dieselbe Durchlesung gilt für .claude/agents und .claude/commands. Für Skills erfordert die Durchlesung Claude Code v2.1.277 oder später.

​

Verwalten Sie Worktrees manuell

git worktree add ../project-feature-a -b feature-a

git worktree add ../project-bugfix fix-issue-456

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

Non-Git-Versionskontrolle

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

​

Fehlerbehebung

​

Claude Code kann den Worktree beim Start nicht betreten

​

Die Worktree-Erstellung schlägt auf einem symlink-Pfad fehl

​

Git LFS-Dateien sind Zeiger-Dateien in einem Worktree, den Claude Code erstellt hat

• Could not read the repository git config to neutralize filter drivers: Claude Code konnte die .git/config des Repositories nicht lesen, zum Beispiel wegen ihrer Berechtigungen. Beheben Sie das und versuchen Sie es erneut.
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): Benennen Sie diesen Filter-Treiber in .git/config um oder entfernen Sie ihn und versuchen Sie es erneut.
• The repository git config has a conditional include (includeIf): Verschieben Sie die Einstellungen, die includeIf in .git/config abruft, direkt in diese Datei, entfernen Sie includeIf und versuchen Sie es erneut. Ein includeIf in Ihrer globalen Git-Konfiguration löst dies nicht aus.
• Git was not run: the repository's own git config sets <key>: Die Meldung benennt einen Schlüssel, der Git LFS auf ein auszuführendes Programm verweist, wie lfs.customtransfer.<name>.path oder lfs.standalonetransferagent. Wenn diese Einstellung Ihnen gehört, verschieben Sie sie in Ihre globale Git-Konfiguration. Wenn Sie sie nicht erkennen, entfernen Sie sie aus der Repository-Konfiguration, da ein Tool oder Checkout, dem Sie nicht vertrauen, sie möglicherweise geschrieben hat. Versuchen Sie es erneut, sobald der Schlüssel aus der Repository-Konfiguration weg ist.

​

Claude Code weigert sich, einen Worktree zu verwenden

• Sagt launch from the parent checkout oder Run the resume from the project checkout: Sie haben Claude Code von innen im Worktree gestartet. Starten Sie stattdessen vom Haupt-Checkout; der Worktree benötigt keine Neuerstellung.
• Sagt it cannot be resumed or re-entered: Nichts in dieser Sitzung garantiert den Worktree von dort, wo Sie gestartet haben. Erstellen Sie ihn neu; das Verzeichnis und seine Arbeit bleiben auf der Festplatte zur manuellen Wiederherstellung, und wenn der Worktree einen Haupt-Checkout hat, funktioniert auch das Fortsetzen von dort.
• Sagt it contains the protected checkout: Das abgelehnte Verzeichnis ist ein übergeordnetes Element Ihres Haupt-Checkouts, wie Ihr Home-Verzeichnis. Löschen Sie es nicht. Ändern Sie den Worktree-Pfad, wie den Pfad, den Ihr WorktreeCreate-Hook zurückgibt, oder das EnterWorktree-Ziel, sodass der Worktree den Checkout nicht enthält.
• Sagt the protected checkout <path> has a .git entry that could not be examined oder has git metadata that could not be resolved: Das Problem ist die Git-Metadaten des Haupt-Checkouts, nicht die des Worktrees. Löschen Sie den Worktree nicht und ignorieren Sie den nachfolgenden Rat der Meldung, ihn neu zu erstellen, was auf diese beiden Enden nicht zutrifft. Reparieren Sie den Haupt-Checkout, zum Beispiel ein Berechtigungsproblem oder eine Git-dubious ownership-Ablehnung auf seinem .git, und versuchen Sie es erneut.
• Sagt its recorded path has a network spelling: Claude Code setzt niemals in einen Worktree auf einem Netzwerkpfad fort. Erstellen Sie den Worktree auf einem lokalen Pfad neu.
• Jedes andere Ende: Die Meldung benennt das Problem und seine Behebung, wie das Entfernen einer core.worktree-Umleitung oder die Neuerstellung des Worktrees; folgen Sie ihr. Bevor Sie ein Verzeichnis löschen, dessen Meldung sagt, dass seine Git-Identität nicht überprüft werden konnte, beheben Sie zunächst die benannte Ursache, zum Beispiel einen Symlink im Pfad des Worktrees oder Git selbst, das nicht ausgeführt wird, da das Verzeichnis gesund sein kann. Wenn Sie neu erstellen, retten Sie zunächst alle Änderungen, die Sie aus dem alten Verzeichnis benötigen; es bleibt auf der Festplatte.

​

Die Sitzung wird außerhalb ihres Worktrees fortgesetzt

• Error: cannot resume into worktree <path>: ...This session was not started. für eine Ablehnung, die die Tabelle als Did not re-enter zeigt. Claude Code löscht die Worktree-Bindung vor dem Beenden, und der Fehler sagt dies; das nächste Mal, wenn Sie die Unterhaltung fortsetzen, wird die Sitzung im aktuellen Verzeichnis ohne Worktree-Isolation fortgesetzt. Vor v2.1.260 schrieb Claude Code das gelöschte Binding nicht, daher schlug jeder Wiederholungsversuch derselben Fortsetzung mit demselben Fehler fehl. Wenn Sie Transkriptschreibvorgänge unterdrücken, kann das Löschen nicht gespeichert werden. Der Fehler sagt dann, dass derselbe Befehl erneut abgelehnt wird, und benennt --fork-session und das Starten einer neuen Unterhaltung als Wege, um ohne den Worktree fortzufahren.
• Error: could not verify worktree <path> for this resume, so the resume was aborted... für Could not verify
• Error: ...The worktree binding is kept. für Could not re-enter
• Notice: the worktree <path> for this session no longer exists... für einen gegangenen Worktree; Claude Code gibt ihn aus und setzt die Sitzung fort, wie eine interaktive Fortsetzung

​

Siehe auch

• Subagents: Delegieren Sie Arbeit an isolierte Agenten innerhalb einer Sitzung
• Sitzungsübergreifendes Messaging: Lassen Sie die Sitzungen in Ihren Worktrees Erkenntnisse aneinander weitergeben
• Agent-Teams: Koordinieren Sie mehrere Claude-Sitzungen automatisch
• Sitzungen verwalten: Benennen, fortsetzen und wechseln Sie zwischen Gesprächen
• Desktop-Parallelsitzungen: Worktree-gestützte Sitzungen in der Desktop-App