Claude Code Worktree — Git-Isolation, damit parallele Agents sich nicht in die Quere kommen
Jede Claude Code-Sitzung oder jeder Subagent erhält seinen eigenen git worktree; Dateiänderungen sickern nicht zwischen ihnen durch; die Bereinigung erfolgt automatisch, wenn nichts zu behalten ist. Dieser Leitfaden behandelt Tools, Konfiguration, Parallelmuster und Fallstricke.
Was ein Worktree ist und warum er zählt
Ein git worktree ist ein zusätzliches Arbeitsverzeichnis, das mit demselben Repo verbunden ist — mit eigenem Arbeitsverzeichnis und Branch, aber gemeinsam genutzter .git-Historie und Remote. Claude Code bindet jede parallele Sitzung oder jeden Subagent an einen eigenen Worktree, sodass Sitzung A, die Feature X entwickelt, und Sitzung B, die Bug Y behebt, niemals die Dateien der anderen überschreiben. Geteilte Git-Metadaten halten Commits, Pushes und Log-Ansichten konsistent.
Das EnterWorktree-Tool & isolation-Konfiguration
Sagen Sie in einer Claude Code-Sitzung einfach „work in a worktree“ und das Modell ruft EnterWorktree auf, um einen zu erstellen. Oder setzen Sie im Frontmatter eines eigenen Subagents isolation: worktree, damit jeder Dispatch dieses Subagents automatisch einen isolierten Worktree erhält. Ab v2.1.x unterstützen auch Hintergrund-Sitzungen worktree bg-Isolation, sodass langlaufende Tasks Ihren Haupt-Dev-Branch nicht mehr blockieren.
/team-build Paralleler Multi-Agent-Modus
Wenn /team-build mehrere Agents gleichzeitig dispatcht, erhält jeder automatisch Worktree-Isolation und kann auf überlappenden Domains arbeiten, ohne in Konflikt zu geraten. Beispiel: Drei Agents arbeiten gleichzeitig: a) Rewrite des Auth-Moduls, b) Hinzufügen von Unit-Tests, c) Schreiben von Migrationsskripten — Dateiänderungen kollidieren nie; Sie mergen am Ende. Das ist der zentrale Engineering-Mehrwert von Worktrees für Agent-Teams.
Automatische Bereinigung, häufige Fallstricke, Team-Konventionen
Beim Verlassen wird ein Worktree ohne Commits und ohne ungetrackte Dateien automatisch zusammen mit seinem temporären Branch entfernt; gibt es Änderungen, werden der Worktree-Pfad und der Branch zurückgemeldet. Häufige Fallstricke: 1) Branch-Namenskollisionen zwischen Agents; 2) ungetrackte Dateien, die die Bereinigung blockieren; 3) Integration in worktree-from-origin-main-Workflows erfordert ein vorheriges Fetching von origin. Teams sollten einen festen Branch-Präfix vereinbaren (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 lediglich ein Commit-Zeiger — das Wechseln erfordert einen checkout, der Dateien überschreibt. Ein Worktree ist ein unabhängiges Arbeitsverzeichnis: Mehrere Branches können gleichzeitig in verschiedene physische Pfade gecheckt werden. Das ist die Voraussetzung für echtes paralleles Agent-Arbeiten.
Verschmutzen die Subagent-Worktrees das Haupt-Repo?
Nein. Worktree-Pfade liegen außerhalb Ihres Haupt-Checkouts, und git führt sie unter .git/worktrees/<id>. Verlassen Sie sie ohne Commits, wird der gesamte Worktree samt temporärem Branch automatisch gelöscht — das Haupt-Repo bleibt sauber.
Kann ich Worktrees mit Claude Code aus China nutzen?
Ja. Worktrees sind lokale Git- und Claude-Code-Client-Funktionen, die auf Ihrem Rechner laufen. Die Modell-Inferenz läuft über das transparente Gateway von QCode – Sie haben damit dieselbe Erfahrung wie Nutzer im Ausland.
Weiterführende Anleitungen
Parallele Claude-Code-Agents über QCode ausführen
QCode bietet von China aus transparenten Zugriff auf alle Claude-Modelle – Worktree-Parallel-Workflows funktionieren ohne zusätzliche Konfiguration.
Starten Sie Ihren QCode-Plan