Claude Code Worktrees: parallele Sessions ohne Konflikte beim Bearbeiten

Claude Code Worktrees erklärt

Git unterstützt Worktrees schon seit Jahren: git worktree add checkt einen Branch in ein zweites Verzeichnis aus, das auf denselben .git-Daten basiert. Darauf baut Claude Code auf. Mit --worktree (oder -w) legt es den Worktree für dich an, startet die Session darin, blockiert Änderungen, die in deinem Haupt-Checkout landen würden, und bietet beim Beenden an aufzuräumen.

Worktrees isolieren Dateien, sonst nichts. Um eine Aufgabe innerhalb einer Unterhaltung auf mehrere Worker zu verteilen, nutze Subagents; einen Vergleich der Optionen findest du unter mehrere Claude-Code-Agenten.

• Standard-Speicherort: .claude/worktrees/<name>/ im Root des Repositorys.
• Standard-Branchname: worktree-<name>. Lässt du den Namen weg, wählt Claude Code einen, etwa bright-running-fox.
• Geteilt mit deinem Checkout: das .git-Verzeichnis (Commits und Branches sind also überall sichtbar), Plugins mit Projekt-Scope und "Nicht mehr fragen"-Freigaben für Berechtigungen.
• Nicht geteilt: alles, was in der .gitignore steht, etwa .env, node_modules und Build-Ausgaben. Ein Worktree ist ein frischer Checkout.

Der Worktree-Workflow Schritt für Schritt

1. Ignoriere den Worktree-Ordner

   Füge .claude/worktrees/ zur .gitignore hinzu, damit Worktree-Dateien in deinem Haupt-Checkout nicht als untracked auftauchen. Wenn du Claude in diesem Repository noch nie gestartet hast, führe zuerst einmal claude aus und bestätige die Vertrauensabfrage für den Workspace; vorher beenden sich interaktive --worktree-Starts sofort.

2. Starte eine Session pro Aufgabe

   Führe claude --worktree <name> für jede Aufgabe in einem eigenen Terminal aus. Mit einem bereits vorhandenen Namen öffnet der Befehl diesen Worktree erneut, statt einen neuen anzulegen. Du kannst Claude auch mitten in der Session bitten, "in einem Worktree zu arbeiten", dann wechselt es mit dem Tool EnterWorktree selbst in einen.

   # Zwei isolierte Sessions, jede in ihrem eigenen Terminal
   claude --worktree feature-auth
   claude --worktree fix-flaky-test
   
   # Einen Worktree aus Pull Request 1234 abzweigen (das # in Anführungszeichen setzen)
   claude --worktree "#1234"
   
   # Worktrees aus git status heraushalten
   echo ".claude/worktrees/" >> .gitignore

3. Nimm die untracked Dateien mit

   Liste ignorierte Dateien, die das Projekt braucht, etwa .env und .env.local, in einer .worktreeinclude-Datei im Root des Repositorys auf, in .gitignore-Syntax. Claude Code kopiert passende Dateien in jeden Worktree, den es anlegt, auch in die von Subagents und der Desktop-App. Installiere danach die Abhängigkeiten im Worktree oder richte ihn über die Einstellungen ein: Dieses Beispiel zweigt von deinem aktuellen Stand ab, nutzt ein einziges node_modules und checkt nur das Web-Package aus.

   {
     "worktree": {
       "baseRef": "head",
       "symlinkDirectories": ["node_modules"],
       "sparsePaths": [".claude", "packages/web"]
     }
   }

4. Lass die Sessions arbeiten

   Solange eine Session isoliert ist, verweigert Claude Code Dateiänderungen, die auf den Haupt-Checkout zielen, Befehle, deren Arbeitsverzeichnis der Haupt-Checkout ist, und Git-Befehle, die dorthin umgeleitet werden (git -C, --git-dir, GIT_DIR). Was ein einfacher Shell-Befehl wie cp schreibt, verfolgt es nicht; Berechtigungen und Sandboxing bleiben also wichtig.

5. Reviewe und merge wie jeden anderen Branch

   Jeder Worktree ist ein ganz normaler Branch. Committe und pushe von dort aus, öffne einen Pull Request und reviewe ihn wie den eines Teamkollegen. Da alle Worktrees .git teilen, ist der Branch sofort auch in deinem Haupt-Checkout sichtbar.

6. Beenden und aufräumen

   Beim Beenden prüft Claude Code den Worktree. Ein sauberer Worktree aus einer unbenannten Session wird samt Branch automatisch entfernt; bei einer benannten Session fragt es vorher. Gibt es Änderungen, untracked Dateien oder neue Commits, fragt es, ob der Worktree bleiben oder weg soll, und gibt einen Befehl claude --worktree <name> --resume aus, mit dem du später zurückkommst.

Quelle: Claude-Code-Dokumentation, Run parallel sessions with worktrees

Worktree-Einstellungen in Claude Code

Alle gehören unter worktree in eine Einstellungsdatei (~/.claude/settings.json, .claude/settings.json oder .claude/settings.local.json).

Claude Code Worktree vs. Branch vs. git worktree

Von Hand mit git worktree

Nimm reines Git, wenn du einen bestimmten bestehenden Branch oder einen Ordner außerhalb des Repositorys willst; worktree.baseRef kann keinen Branch benennen. Plugins und Berechtigungsfreigaben teilt Claude Code auch mit diesen Worktrees.

1. Worktree anlegen, Claude starten, danach entfernen

   Ersetze feature-a durch einen neuen Branchnamen oder lass -b weg, um einen bereits vorhandenen Branch auszuchecken.

   git worktree add ../app-feature-a -b feature-a
   cd ../app-feature-a && claude
   git worktree list
   git worktree remove ../app-feature-a

Subagents und Hintergrund-Sessions in Worktrees

• Bitte Claude, "für deine Agenten Worktrees zu verwenden", oder ergänze isolation: worktree im Frontmatter eines eigenen Subagents in .claude/agents/; dann arbeitet jeder Subagent in seinem eigenen temporären Worktree.
• Der Worktree eines Subagents ohne Änderungen wird entfernt, sobald der Subagent fertig ist. Einer mit Änderungen bleibt, bis ein regelmäßiger Aufräumlauf ihn nach cleanupPeriodDays entfernen kann, ohne dass Arbeit verloren geht.
• Hintergrund-Sessions (claude --bg) ändern standardmäßig nur innerhalb eines Worktrees; starte eine mit claude --bg --worktree oder setze worktree.bgIsolation auf "none".
• Schalte in der Desktop-App unter dem Eingabefeld Worktree ein, bevor du eine Session startest.

Worktrees aufräumen und typische Probleme

• Starts mit claude -p --worktree haben keine Abfrage beim Beenden und lassen ihre Worktrees deshalb liegen. Entferne sie mit git worktree remove, vorher mit git worktree unlock, falls Git sie als gesperrt meldet.
• Can only use --worktree in a git repository: Führe git init aus und lege einen ersten Commit an, oder richte einen WorktreeCreate-Hook für SVN, Perforce oder Mercurial ein.
• Git-LFS-Dateien erscheinen als Pointer-Dateien, wenn LFS mit --local installiert wurde: Führe git lfs pull im Worktree aus.
• Claude Code legt keinen Worktree an, wenn .claude oder .claude/worktrees ein Symlink ist.
• In Hooks zeigt ${CLAUDE_PROJECT_DIR} weiter auf den Haupt-Checkout; den Worktree-Pfad liefert das Feld cwd der Hook-Eingabe.
• Ein Worktree mit Basis "fresh" ohne eigene Commits oder mit bereits gemergtem PR wird auf den Standard-Branch zurückgesetzt, wenn du ihn über seinen Namen erneut öffnest.

Worktrees halten Sessions auseinander. Crewmark hält sie beschäftigt.

Worktrees lösen das Kollisionsproblem, aber jede Session bleibt untätig, bis du etwas tippst. Crewmark macht aus einer Session von Claude Code, Codex, DeepSeek Harness oder OpenCode einen KI-Mitarbeiter mit Rolle, Ziel und Arbeitszeiten und weckt ihn per Heartbeat, damit er das nächste Issue von einem Board übernimmt.

1. Ein Mitarbeiter pro Worktree

   Gib jedem Mitarbeiter einen eigenen Worktree und eine eigene Rolle, etwa einem Programmierer und einem Reviewer im selben Repository, wie bei mehreren Claude-Code-Agenten.

2. Lass den Heartbeat die Arbeit starten

   Während seiner Arbeitszeiten wacht jeder Mitarbeiter alle 15, 30 oder 60 Minuten in derselben Unterhaltung auf; siehe wie du Claude Code proaktiv machst.

3. Weise Issues zu und reviewe Branches

   Lege Arbeit auf das Board; jeder Mitarbeiter übernimmt ein Issue, committet auf seinem eigenen Branch und schreibt dir, wenn er eine Entscheidung braucht. Lies, was ein KI-Mitarbeiter ist.

FAQ zu Claude Code Worktrees