Git Worktrees: die Grundlage, um mehrere KI-Agenten ohne Konflikte laufen zu lassen

Du startest zwei Agenten auf demselben Repo. Der eine ändert package.json, der andere auch. Dreißig Sekunden später ist dein Code in einem Zustand, den niemand mehr mergen kann.

Das ist kein Bug in deinen Agenten. Es liegt daran, dass sie alle im selben Ordner arbeiten.

Die Lösung ist ein Tool, das Git seit Jahren mitbringt und fast niemand nutzt: git worktree.

Das Problem: 3 Agenten, 1 Repo, unmöglicher Merge

Ein normales Git-Repo ist ein Ordner mit genau einem ausgecheckten Branch. Du arbeitest auf main, du wechselst den Branch, und der ganze Ordner stellt sich um.

Jetzt wirf drei autonome Agenten in diesen Ordner. Sie schreiben gleichzeitig. Agent A legt eine Datei an, Agent B macht git checkout, um sauber zu starten, und löscht damit die angefangene Arbeit von A. Am Ende hast du halb geschriebene Dateien, einen kaputten Index und Konflikte, die länger zum Entwirren brauchen, als wenn du es selbst gecodet hättest.

Parallelität spart dir nur dann Zeit, wenn sich die Agenten nicht gegenseitig in die Quere kommen.

Was ein Git Worktree ist

Ein Worktree ist ein zweiter Arbeitsordner, der am selben Repo hängt.

Gleiche History, gleiches Remote, aber jeder Worktree hat seinen eigenen ausgecheckten Branch und seine eigenen Dateien auf der Platte. Du kannst fünf nebeneinander haben, jeden auf einem anderen Branch, ohne dass sie sich in die Quere kommen.

Ein .git, mehrere Workspaces. Mehr ist es nicht.

Ein Worktree pro Agent, in der Praxis

So sieht das Setup aus. Aus deinem Repo heraus:

git worktree add ../project-auth -b feature/auth
git worktree add ../project-billing -b feature/billing
git worktree add ../project-export -b feature/export

Du hast gerade drei Ordner erstellt, jeden auf seinem eigenen Branch. In jedem startest du einen Agenten:

cd ../project-auth && claude
cd ../project-billing && codex

Jeder Agent hat seinen Ordner, seinen Branch, seine Dateien. Der Auth-Agent bekommt nie zu sehen, was der Billing-Agent macht. Keine Kollision möglich.

Wenn ein Feature fertig ist, reviewst du seinen Branch und mergst ihn. Danach räumst du auf:

git worktree remove ../project-auth

Der Ordner ist weg, der Branch bleibt in deiner History. Sauber.

Die 3 Fallen, die du kennen solltest

Erste Falle: die gemeinsame zentrale Datei. Wenn zwei Features beide dieselbe routes.ts oder dasselbe Datenbankschema anfassen müssen, retten dich Worktrees nicht, der Konflikt kommt beim Mergen. Ein Agent fasst die Dateien an, die alle teilen, die anderen warten oder bauen einen Umweg.

Zweite Falle: Branches, die abdriften. Während deine Agenten arbeiten, läuft main weiter. Drei Tage später hängen deine Branches hinterher und das Mergen wird zur Qual. Rebase früh und oft, oder halte die Sessions kurz.

Dritte Falle: vergessenes Aufräumen. Jeder Worktree ist ein echter Ordner auf deiner Platte. Zehn am Tag ohne Aufräumen, und dein übergeordneter Ordner wird unübersichtlich. git worktree list zeigt dir, was so herumliegt, git worktree prune entfernt die toten.

Die vierte Falle: ein Worktree startet leer

Ein Worktree enthält nur die Dateien, die Git verfolgt. git worktree add gibt dir den Quellcode, nicht node_modules, nicht das .venv, nicht die .env mit deinen lokalen Secrets, nicht den Build-Cache. Ein Agent, der in einem frischen Worktree startet, kann die Tests nicht ausführen, kann den Dev-Server nicht starten und sagt oft nicht, warum: npm test scheitert an einem fehlenden Modul, die App scheitert an einer fehlenden Umgebungsvariable, und der Agent verbringt seine ersten zehn Minuten mit Klempnerarbeit statt mit dem Ticket.

Das ist uns selbst passiert. Ein Nutzer hat uns darauf hingewiesen, dass die Worktree-Option in AgentsRoom in den erweiterten Optionen des Agentenformulars versteckt war und dass jeder Agent, der in einem Worktree gestartet wurde, keine einzige Abhängigkeit hatte und keinen einzigen Test ausführen konnte. Beides stimmte. Die Isolation existierte, war aber ohne einen manuellen Schritt, an den sich niemand erinnerte, unbrauchbar.

Seit Version 1.194.0 sitzt die Option in einem Block „Isolation“ des Agentenformulars, sichtbar, ohne etwas aufzuklappen, und der erste Agent, der in einem frischen Worktree startet, findet ihn vorbereitet vor: AgentsRoom kopiert aus dem Haupt-Checkout die ignorierten Dateien, die zu einem Muster passen (standardmäßig alle .env*, ohne je etwas zu überschreiben, nie nach node_modules oder .git), und führt dann den Installationsbefehl aus, der anhand der Lockfile erkannt wird (bun, pnpm, yarn, npm, uv, poetry, pipenv, bundle, composer), oder den, den du in den Projekteinstellungen festgelegt hast. Der Befehl läuft im eigenen Terminal des Agenten, du siehst ihn also, und eine fehlgeschlagene Installation hält den Agenten nicht vom Starten ab. Das passiert einmal pro Worktree: Eine Markierung im privaten Git-Ordner des Worktrees sorgt dafür, dass der nächste Start den Schritt überspringt.

Wenn du das von Hand machst, ist das Rezept dasselbe und passt in ein Skript: .env* kopieren, die Installation ausführen, dann den Agenten starten. Pack git worktree add mit hinein, sonst vergisst du es beim dritten Agenten.

Die eigentliche Frage: wer behält die fünf Ordner im Blick?

Worktrees lösen Dateikollisionen. Sie lösen nicht deine mentale Last.

Du hast fünf Ordner, fünf Agenten, fünf Terminals. Welcher wartet auf dein Review? Welcher ist vor zehn Minuten fertig geworden, während du woanders hingeschaut hast? Welcher ist abgestürzt?

Genau hier stößt ein Worktree pro Agent an seine Grenze, wenn du im Terminal bleibst. Du hast den technischen Konflikt gelöst, aber die Zahl der Fenster, die du im Auge behalten musst, hat sich vervielfacht.

AgentsRoom packt jeden Agenten auf eine Kachel, mit seinem Status und seiner Farbe, egal in welchem Worktree er läuft. Ein Agent, der wartet, wird rot und pingt dich an. Lies wie du 3 bis 8 Agenten parallel laufen lässt, ohne den Überblick zu verlieren für die komplette Methode, die du auf Worktrees aufsetzt.

Was du mitnehmen solltest

Ein Agent, ein Worktree, ein Branch. Das ist die Grundregel für ernsthaftes Arbeiten mit mehreren Agenten.

Die Befehle passen in drei Zeilen, der Nutzen ist sofort da: deine Agenten hören auf, sich gegenseitig zu überschreiben. Pack eine Ansicht obendrauf, die dir sagt, welcher dich braucht, und du kannst wirklich fünf Aufgaben parallel stemmen, ohne den Verstand zu verlieren.