Git Worktrees mit KI-Coding-Agents nutzen

Der zuverlässige Weg, mehrere KI-Coding-Agents auf einem einzigen Repository laufen zu lassen, lautet: eine Aufgabe, ein Branch, ein Worktree, ein Agent. Jeder Agent erhält sein eigenes, mit git worktree add erstelltes Verzeichnis, arbeitet auf seinem eigenen Branch und fasst niemals Dateien an, die ein anderer Agent gerade bearbeitet.

Die meisten Entwickler kommen auf die harte Tour zu diesem Muster. Zwei Agents in einem Checkout überschreiben klammheimlich die halbfertigen Änderungen des jeweils anderen, oder ein Agent verkeilt sich beim Versuch, einen Branch auszuchecken, der bereits anderswo ausgecheckt ist. In diesem Artikel geht es speziell um den Agent-Workflow: was das Muster isoliert, was es bewusst nicht isoliert und was zu tun ist, wenn drei Agents gleichzeitig fertig werden.

Das Git-Worktree-Muster für KI-Agents

Das Muster „ein Agent pro Worktree“ braucht zwei Befehle pro Aufgabe. Erstellen Sie einen Worktree mit einem frischen Branch auf Basis von main und starten Sie darin einen Agent:

git worktree add ../task-a -b agent/task-a main
git worktree add ../task-b -b agent/task-b main

Richten Sie einen Agent auf ../task-a aus und einen weiteren auf ../task-b. Jeder hat sein eigenes Arbeitsverzeichnis, seinen eigenen Index und seinen eigenen HEAD, während alle Worktrees dieselbe Objektdatenbank und dieselben Refs teilen – Commits aus einem Worktree sind also sofort in den anderen sichtbar. Binden Sie den Worktree an die Aufgabe, nicht an den Agent: erstellen, wenn die Arbeit beginnt, löschen, wenn der Branch gemergt ist. Anthropic dokumentiert genau diese manuelle Abfolge im Worktrees-Guide von Claude Code, und Cursor führt Agents in isolierten Worktrees aus – gesteuert über das Agents Window. Codex arbeitet genauso, wenn man es auf ein Verzeichnis ansetzt.

Warum scheitert ein einziges gemeinsames Verzeichnis?

Zwei Agents in einem Verzeichnis scheitern lautlos: Weder Git noch die Agents melden einen Fehler, wenn einer die nicht committeten Änderungen des anderen überschreibt – der Schaden zeigt sich erst beim Review. Gits Konflikterkennung vergleicht Commits; parallele Schreibzugriffe auf denselben Working Tree erreichen sie nie.

Der zweite Fehlerfall ist lauter, aber schlimmer. Gleichzeitige Git-Operationen in einem gemeinsamen Verzeichnis kollidieren an .git/index.lock, und wenn ein Agent abstürzt, während er den Lock hält, blockiert die verwaiste Datei sämtliche Git-Befehle aller anderen Agents, bis jemand sie von Hand löscht. Manche Agents versuchen es erneut; andere geben das Committen auf und generieren weiter Code auf einem unbegrenzt anwachsenden, nicht committeten Zustand. Getrennte Worktrees lösen beide Probleme auf, weil jeder Worktree gegen seinen eigenen Index staged statt gegen einen gemeinsamen.

Was ein neuer Worktree nicht enthält

Ein neuer Worktree enthält ausschließlich versionierte Dateien – node_modules, .env, Build-Caches und alles andere, was per gitignore ausgeschlossen ist, fehlt also, bis Sie es anlegen. Ein Agent, der in einem nackten Worktree startet, wird beim ersten Testlauf scheitern oder – schlimmer – „hilfsbereit“ die Konfiguration umschreiben, um das auszugleichen. Bootstrappen Sie jeden Worktree, bevor der Agent startet:

cd ../task-a
npm ci
cp ../main-repo/.env .env

npm ci ist hier die richtige Installationsmethode: Es ist für saubere Umgebungen gebaut und installiert exakt das, was die Lockfile vorgibt. Wenn Ihr Agent Claude Code ist, kann eine .worktreeinclude-Datei gitignorierte Dateien wie .env in die von Claude Code selbst erstellten Worktrees übernehmen – sie greift jedoch nicht für Worktrees, die Sie von Hand mit git worktree add anlegen. Das manuelle Kopieren funktioniert dagegen mit jedem Tool.

Was Worktrees nicht isolieren

Worktrees isolieren Dateien, nicht die Laufzeitumgebung: Ports, Datenbanken, Docker-Volumes und gemeinsame Caches gehören der Maschine. Zwei Dev-Server, die aus zwei Worktrees gestartet werden, streiten sich also weiterhin um Port 3000. Die Verzeichnisgrenze bedeutet nichts für alles, was über Hostname oder Port adressiert wird.

Geben Sie jedem Worktree einen eigenen Port und eine eigene Datenbank, bevor Sie einen Agent starten, der Migrationen ausführt – denn eine Schemaänderung aus einem Worktree landet in jeder Datenbank, die die anderen mitbenutzen. Setzen Sie beides in der kopierten .env:

# ../task-a/.env
PORT=3001
DATABASE_URL=postgres://localhost:5432/app_agent_task_a

Wenn Sie die Datenbank nach dem Branch benennen, lassen sich veraltete Datenbanken später leicht erkennen und löschen. Container können auch die Laufzeitebene isolieren, aber die damit verbundenen Abwägungen füllen einen eigenen Artikel.

Wie sagt man dem Agent, dass er sich in einem Worktree befindet?

Ein Branch kann immer nur in einem Worktree gleichzeitig ausgecheckt sein. Ein Agent, der per git checkout main synchronisieren will, erhält also einen Fehler und bleibt häufig stecken. Das Handbuch zu git checkout beschreibt dieses Verhalten und nennt --ignore-other-worktrees als Möglichkeit, es zu übergehen. Lassen Sie den Agent das nicht zur Laufzeit herausfinden – schreiben Sie es in die Instruktionsdatei, die der Agent liest (AGENTS.md, CLAUDE.md oder Äquivalent):

You are working inside a git worktree.
Stay on the current branch. Never run `git checkout` or `git switch`.
To sync with main, run `git fetch origin` and `git rebase origin/main`.

Wenn ein Agent lediglich einen bestimmten Commit lesen oder bauen muss, überspringen Sie Branches komplett: git worktree add --detach erstellt einen Worktree mit losgelöstem HEAD und umgeht damit die Exklusivitätsregel vollständig.

git worktree add --detach ../review-b1a2c3 b1a2c3

Wie merged man, was zurückkommt?

Worktrees beseitigen keine Merge-Konflikte; sie verlagern sie von stillen Überschreibungen zur Laufzeit hin zu sichtbaren Konflikten beim Merge, wo das übliche Git-Werkzeug sie abfängt. Wenn mehrere Agents gleichzeitig fertig werden, integrieren Sie seriell: einen Branch mergen, den nächsten auf den aktualisierten main rebasen, mergen, wiederholen.

cd ../main-repo
git merge agent/task-a

cd ../task-b
git rebase main
cd ../main-repo
git merge agent/task-b

Jeder Rebase legt Konflikte gegenüber allem bereits Gemergten offen – Branch für Branch, statt dreifache Überraschungen aufzustapeln. Die Reihenfolgeregel greift bereits vor dem Merge: Aufgaben, die dieselben Dateien berühren oder bei denen eine den Output der anderen konsumiert, werden sequenziert statt parallelisiert. Keine Worktree-Anordnung repariert eine Aufgabenzerlegung, die nie unabhängig war.

Wie viele Agents – und wann aufräumen?

Die praktische Obergrenze ist weder Git noch Speicherplatz, sondern Ihre Review-Kapazität: Jeder parallele Agent produziert einen Branch, den Sie lesen, testen und mergen müssen. Teams, die über diesen Workflow publizieren – etwa das Engineering-Team von incident.io – berichten von vier oder fünf gleichzeitig laufenden Agents, und den meisten Entwicklern reichen weniger vollkommen aus. Wenn ein Branch gemergt ist, führen Sie git worktree remove ../task-a aus; da das Bootstrapping nicht versionierte Dateien hinzugefügt hat, werden Sie voraussichtlich --force benötigen, das git worktree remove bei unsauberen Worktrees verlangt. Wurde ein Verzeichnis stattdessen mit rm -rf gelöscht, räumt git worktree prune die veralteten Metadaten auf, die Git noch vorhält.

Der Einstieg mit zwei Agents

Eine Aufgabe, ein Branch, ein Worktree, ein Agent – damit werden parallele Agents von einer Quelle stiller Datenkorruption zu einer Menge reviewbarer Branches. Fangen Sie mit zweien an: Worktrees erstellen, jeden mit npm ci und einer aufgabenspezifischen .env bootstrappen, die Anweisung zum Verbleib auf dem Branch ergänzen und die Abfolge aus Rebase und Merge einüben, bevor Sie über das hinaus skalieren, was Sie tatsächlich reviewen können.

FAQs

Sollte ich Git-Worktrees oder separate Clones verwenden, um KI-Agents parallel zu betreiben?

Worktrees sind in der Regel die bessere Wahl, weil sie sich eine Objektdatenbank teilen: Ein in einem Worktree erstellter Commit ist sofort in den anderen sichtbar, ohne Push oder Fetch, und die Historie liegt nur einmal auf der Platte. Separate Clones duplizieren die vollständige Historie und benötigen Push und Fetch, um Commits auszutauschen. Clones sind nur dann im Vorteil, wenn Sie vollständige Isolation brauchen, etwa bei Repositories mit Submodulen.

Funktionieren Git-Worktrees mit Repositories, die Submodule verwenden?

Nur teilweise. Gits eigenes Worktree-Handbuch führt die Submodul-Unterstützung unter BUGS, bezeichnet mehrfaches Auschecken als experimentell und rät davon ab, ein Superprojekt an mehr als einer Stelle gleichzeitig auszuchecken. Ein Worktree mit Submodulen lässt sich zudem nicht per git worktree move verschieben. Für parallele Agents auf einem Repository mit Submodulen sind separate vollständige Clones der sicherere Isolationsmechanismus – auch wenn sie die Historie duplizieren und ein Push nötig ist, um Commits zwischen den Checkouts auszutauschen.

Teilen sich alle Git-Worktrees dieselbe Git-Konfiguration?

Ja. Jeder Worktree liest dieselbe Repository-Konfiguration, sofern Sie das nicht ausdrücklich abwählen. Um einem Worktree eigene Einstellungen zu geben, führen Sie git config extensions.worktreeConfig true aus und schreiben Werte anschließend mit git config --worktree, was sie in der worktree-eigenen Datei config.worktree ablegt. Der Nachteil: Ältere Git-Versionen öffnen ein Repository nicht mehr, sobald die Extension aktiviert ist.

Löscht das Entfernen eines Worktrees den Branch des Agents?

Nein. Branches sind Refs, die im gesamten Repository geteilt werden – git worktree remove löscht also das Arbeitsverzeichnis und dessen Metadaten, lässt den Branch und sämtliche Commits darauf jedoch unangetastet. Verloren gehen nur die nicht committeten Änderungen in diesem Verzeichnis, weshalb remove unsaubere Worktrees verweigert, solange Sie nicht --force übergeben. Den Branch löschen Sie nach dem Merge separat mit git branch -d.