We earn commissions when you shop through the links below. (Affiliate-Hinweis)

Blog · 28. Oktober 2026

Git Worktrees für parallele KI-Agenten: Claude Code, Cursor & Codex

Stand: 28. Oktober 2026 · Befehle und Verhalten gegen die offiziellen Docs von Git, Anthropic, Cursor und OpenAI geprüft

Sobald du zwei Agents gleichzeitig auf dasselbe Repo loslässt, wird es chaotisch: Einer baut ein Feature, der andere fixt einen Bug, und beide schreiben in dieselben Dateien. Die Lösung, auf die sich Claude Code, Cursor und Codex inzwischen alle stützen, heißt Git Worktree. Hier steht, was das ist, wie du es in jedem der drei Tools startest und worauf du achten musst, damit am Ende nichts verloren geht.

Was ist ein Git Worktree?

Ein Worktree ist ein zweites (oder drittes, viertes …) Arbeitsverzeichnis für dasselbe Repository. Jeder Worktree hat seine eigenen Dateien und seinen eigenen Branch, teilt sich aber Commits, Branches und Remote mit deinem normalen Checkout. Für Agents heißt das: Jeder bekommt seine eigene Kopie zum Editieren, und dein Haupt-Checkout bleibt unangetastet.

Ohne KI-Tool sieht das so aus:

# neuen Worktree mit neuem Branch anlegen
git worktree add -b fix-login ../meinprojekt-fix-login

# alle Worktrees anzeigen
git worktree list

# Worktree wieder entfernen (--force, wenn noch Änderungen drin sind)
git worktree remove ../meinprojekt-fix-login

# Verwaiste Einträge aufräumen
git worktree prune

Eine Regel solltest du kennen: Git lässt denselben Branch nicht in zwei Worktrees gleichzeitig ausgecheckt zu. Versuchst du es trotzdem, kommt fatal: 'feature/a' is already used by worktree at …. Das ist kein Bug, sondern Schutz vor verlorenen Commits.

Claude Code: --worktree

claude --worktree feature-auth
# zweites Terminal, zweiter Agent:
claude --worktree bugfix-123
  • Claude legt den Worktree unter .claude/worktrees/<name>/ an, auf einem neuen Branch worktree-<name>. Ohne Namen erfindet Claude einen. Kurzform: -w.
  • Das Repo braucht mindestens einen Commit, sonst bricht der Befehl ab. Interaktiv muss der Ordner einmal per claude als vertrauenswürdig bestätigt sein; claude -p --worktree überspringt diesen Check.
  • Standardmäßig startet der Worktree vom Default-Branch des Remotes (meist main). Willst du von deinem aktuellen Stand abzweigen, setz in den Settings "worktree": { "baseRef": "head" }.
  • Pull Requests direkt prüfen: claude --worktree "#1234" holt den Head-Commit des PRs von origin.
  • Auch Subagents können isoliert laufen: isolation: worktree im Frontmatter eines Agents in .claude/agents/.
  • Beim Beenden prüft Claude, ob noch Arbeit im Worktree liegt, und fragt, ob er bleiben soll. Läufe mit -p räumen dagegen nicht auf; das machst du mit git worktree remove.

Tipp aus den Docs: .claude/worktrees/ in die .gitignore, damit die Worktrees nicht als ungetrackte Dateien im Haupt-Checkout auftauchen.

Cursor: /worktree und /best-of-n

/worktree fix the failing auth tests and update the login copy

/best-of-n sonnet,gpt,composer fix the flaky logout test
  • /worktree verlegt den Rest des Chats in einen eigenen Checkout. Danach kannst du direkt aus dem Worktree committen und pushen, mit /apply-worktree die Änderungen in deinen Haupt-Checkout holen oder mit /delete-worktree alles verwerfen.
  • /best-of-n lässt dieselbe Aufgabe mit mehreren Modellen laufen, jedes in seinem eigenen Worktree. Gemergt wird nichts automatisch: Du suchst den Gewinner aus. Achtung, jedes Modell verbraucht dabei eigenes Kontingent.
  • Im Agents Window gibt es Worktrees direkt in der Oberfläche. In der IDE laufen sie über die Slash-Befehle oben.
  • Setup pro Worktree (Dependencies, .env kopieren, Migrationen) steuerst du mit .cursor/worktrees.json und den Keys setup-worktree, setup-worktree-unix und setup-worktree-windows.
// .cursor/worktrees.json
{
  "setup-worktree": ["npm ci", "cp $ROOT_WORKTREE_PATH/.env .env"]
}

$ROOT_WORKTREE_PATH zeigt dabei auf deinen Haupt-Checkout; das Beispiel stammt so aus den Cursor-Docs. Dependencies per Symlink in den Worktree zu holen, empfiehlt Cursor ausdrücklich nicht.

Codex (ChatGPT-Desktop-App): Worktree und Handoff

  • Beim Start eines Chats wählst du unter dem Eingabefeld Worktree und den Branch, von dem aus gestartet wird. Codex legt den Worktree unter $CODEX_HOME/worktrees an, im Zustand „detached HEAD“, also ohne eigenen Branch. Uncommittete Änderungen des gewählten Branches nimmt Codex mit.
  • Fertig? Entweder Create branch here und direkt aus dem Worktree pushen, oder per Hand off den Chat samt Code in deinen lokalen Checkout holen.
  • Codex behält standardmäßig die letzten 15 verwalteten Worktrees und löscht ältere automatisch, vorher wird ein Snapshot gespeichert. Gepinnte und laufende Chats sind geschützt.
  • Worktrees gibt es laut Docs nur in Codex in der ChatGPT-Desktop-App.

Der Klassiker: .env fehlt im Worktree

Ein Worktree enthält nur, was in Git eingecheckt ist. Deine .env, node_modules oder lokale Configs fehlen also. Claude Code und Codex lesen dafür beide eine .worktreeinclude im Repo-Root (Syntax wie .gitignore). Kopiert werden nur Dateien, die passen und von Git ignoriert werden:

# .worktreeinclude
.env
.env.local
config/secrets.json

Dependencies installierst du pro Worktree neu (oder lässt den Agent das machen). In Cursor übernimmt das die .cursor/worktrees.json.

Worauf du achten solltest

  • Speicherplatz: Jeder Worktree hat seine eigenen Dateien, Dependencies und Build-Caches. Fünf Agents mit je eigenem node_modules merkt man auf der SSD.
  • Kosten: Vier parallele Agents verbrauchen ungefähr viermal so viel Kontingent wie einer. Wie schnell das bei Cursor, Claude Code oder Codex ins Geld geht, rechnest du im KI-Coding-Kostenrechner durch.
  • Isolation ist nicht Sicherheit: Ein Worktree trennt Dateien, keine Rechte. Claude Code blockiert zwar Edits und Git-Befehle in Richtung Haupt-Checkout, aber laut Docs nicht jedes cp oder jede Shell-Umleitung. Wer Agents wirklich abschotten will, lässt sie auf einem eigenen Server laufen (siehe KI-Coding-Agent auf dem eigenen VPS).
  • Aufräumen: Ab und zu git worktree list ausführen. Alte Worktrees mit ungesicherter Arbeit löscht keins der Tools ungefragt, deshalb bleiben sie gerne liegen.

Fazit

Wenn du mehr als einen Agent gleichzeitig laufen lässt, sind Worktrees Pflicht. In Claude Code reicht claude -w name, in Cursor /worktree oder /best-of-n, in Codex der Worktree-Schalter beim Chat-Start. Leg einmal eine .worktreeinclude an, behalte den Plattenplatz im Blick und räum alte Worktrees weg. Dann können die Agents parallel arbeiten, ohne sich gegenseitig die Dateien zu überschreiben.

Mehr zum Thema: Cursor vs Claude Code, Claude Code: Abo oder API? und KI-Coding-Agent auf dem eigenen VPS.

Quellen

KostenrechnerAlle Blog-ArtikelDigest-Archiv

Fragen / Korrekturen: kontakt@syntaxlabor.de