Claude Code Worktree — Git-Isolation, damit parallele Agents sich nicht in die Quere kommen
Stand 2026-10-20 isoliert Claude Code parallele Sitzungen mit git worktrees: claude --worktree feature-auth legt ein Arbeitsverzeichnis unter .claude/worktrees/ mit Branch worktree-feature-auth an; Subagents können isolation: worktree setzen. Beim Beenden prüft Claude, was verloren ginge.
Was ein Worktree ist und warum er zählt
Ein git worktree ist ein zusätzliches Arbeitsverzeichnis desselben Repos mit eigenen Dateien und eigenem Branch, das .git-Historie und Remote mit dem Haupt-Checkout teilt. Claude Code startet jede parallele Sitzung in ihrem eigenen worktree: claude --worktree feature-auth (oder -w) erstellt .claude/worktrees/feature-auth/ im Repo-Stamm auf dem Branch worktree-feature-auth. Sitzung A schreibt Feature X, Sitzung B behebt Bug Y, ohne die Dateien der anderen zu berühren.
Das EnterWorktree-Tool & isolation-Konfiguration
Sie können Claude in einer Sitzung auch bitten, in einem worktree zu arbeiten; er erstellt ihn mit dem EnterWorktree-Tool. Ein Pfad außerhalb von .claude/worktrees/ erfordert vorher eine Zustimmung (vor v2.1.206 konnte Claude jeden vorhandenen worktree ohne Nachfrage betreten). Ein eigener Subagent erhält mit isolation: worktree im Frontmatter bei jedem Dispatch einen temporären worktree. Nehmen Sie .claude/worktrees/ in .gitignore auf; .worktreeinclude übernimmt .env und andere ignorierte Dateien in neue worktrees.
Subagent-Worktrees und parallele Agents
Subagents können jeweils in ihrem eigenen worktree laufen: Bitten Sie Claude, „use worktrees for your agents“ zu verwenden, oder setzen Sie isolation: worktree bei einem eigenen Subagent. Jeder Subagent erhält einen temporären worktree, der nach Abschluss ohne Änderungen automatisch entfernt wird; einer mit Änderungen bleibt auf der Platte, bis die periodische Bereinigung ihn ohne Arbeitsverlust entfernen kann. Beispiel: Drei Agents schreiben gleichzeitig auth um, ergänzen Unit-Tests und schreiben Migrationen — Dateiänderungen kollidieren nicht, Sie mergen am Ende.
Automatische Bereinigung, häufige Fallstricke, Team-Konventionen
Wenn Sie eine interaktive Worktree-Sitzung beenden, prüft Claude geänderte und nicht verfolgte Dateien sowie neue Commits: Eine saubere unbenannte Sitzung wird automatisch entfernt, bei einer benannten fragt Claude zuerst nach, und bei Änderungen fragt Claude, ob sie behalten oder entfernt werden soll; -p-Läufe werden nicht automatisch bereinigt. Häufige Fallstricke: 1) Kollisionen von Branch-Namen zwischen Agenten; 2) Subagent-Worktrees mit Änderungen bleiben bis zur periodischen Bereinigung auf der Festplatte; 3) .claude/worktrees/ wurde nicht in .gitignore eingetragen. Legen Sie im Team ein festes Branch-Präfix fest (z. B. wt/agent-<name>-<ts>), um Kollisionen zu vermeiden.
FAQ
Wie unterscheidet sich ein Worktree von einem regulären git Branch?
Ein Branch ist ein Commit-Zeiger; beim Wechseln überschreibt ein checkout die Dateien. Ein worktree ist ein eigenes Arbeitsverzeichnis, daher können mehrere Branches gleichzeitig in verschiedene physische Pfade ausgecheckt werden. Das ist die Voraussetzung für parallele Agent-Arbeit.
Verschmutzen die Subagent-Worktrees das Haupt-Repo?
Nein. Jeder Subagent erhält einen temporären worktree; git führt sie unter .git/worktrees/<id>. Ein Subagent-worktree ohne Änderungen wird automatisch entfernt; einer mit Änderungen bleibt, bis die Bereinigung ihn ohne Arbeitsverlust entfernen kann. Der Haupt-Checkout bleibt sauber.
Kann ich Worktrees mit Claude Code aus China nutzen?
Ja. Worktrees sind lokale git- und Claude-Code-Client-Funktionen; die Modell-Inferenz läuft über den konfigurierten QCode-Endpunkt. Worktrees erfordern ein git-Repository; für andere Versionskontrollsysteme ersetzen WorktreeCreate- und WorktreeRemove-Hooks die git-Logik.
Weiterführende Anleitungen
Parallele Claude-Code-Agents über QCode ausführen
Die Modell-Inferenz läuft über den API-Endpunkt von QCode, worktrees laufen lokal; parallele Sitzungen starten mit den Befehlen oben.
Starten Sie Ihren QCode-Plan