Git worktrees: de basis voor het uitvoeren van meerdere AI-agents zonder conflicten

Je start twee agenten op dezelfde repo. De een bewerkt package.json, de ander ook. Dertig seconden later is je code in een staat die niemand kan mergen.

Dat is geen bug in je agenten. Het is dat ze allemaal in dezelfde map werken.

De oplossing is een tool die Git al jaren heeft en die bijna niemand gebruikt: git worktree.

Het probleem: 3 agenten, 1 repo, onmogelijke merge

Een normale Git-repo is één map met één branch die tegelijkertijd is uitgecheckt. Je werkt op main, je wisselt van branch, de hele map verandert.

Nu zet je drie autonome agenten in die map. Ze schrijven tegelijkertijd. Agent A maakt een bestand aan, agent B voert git checkout uit om schoon te beginnen en wist A's werk in uitvoering. Je eindigt met half geschreven bestanden, een verwoeste index en conflicten die langer duren om op te lossen dan wanneer je het zelf had gecodeerd.

Parallelisme bespaart je alleen tijd als de agenten elkaar niet aanraken.

Wat een git worktree is

Een worktree is een tweede werkmap die aan dezelfde repo is gekoppeld.

Dezelfde geschiedenis, dezelfde remote, maar elke worktree heeft zijn eigen branch uitgecheckt en zijn eigen bestanden op schijf. Je kunt er vijf naast elkaar hebben, elk op een andere branch, zonder dat ze elkaar in de weg zitten.

Eén .git, meerdere werkruimtes. Dat is het.

Eén worktree per agent, in de praktijk

Hier is de setup. Vanuit je repo:

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

Je hebt zojuist drie mappen gemaakt, elk op zijn eigen branch. Je start een agent in elk:

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

Elke agent heeft zijn map, zijn branch, zijn bestanden. De auth-agent zal nooit zien wat de billing-agent doet. Geen botsing mogelijk.

Wanneer een feature klaar is, beoordeel je de branch en merge je. Dan ruim je op:

git worktree remove ../project-auth

De map is weg, de branch blijft in je geschiedenis. Schoon.

De 3 valkuilen om te kennen

Eerste valkuil, het gedeelde centrale bestand. Als twee features beide hetzelfde routes.ts of hetzelfde databaseschema moeten aanpassen, redden worktrees je niet, je krijgt de conflict bij het mergen. Eén agent raakt de bestanden aan die iedereen deelt, de anderen wachten of werken eromheen.

Ten tweede, branches die afdrijven. Terwijl je agenten werken, gaat main verder. Drie dagen later lopen je branches achter en wordt mergen pijnlijk. Rebase vroeg en vaak, of houd sessies kort.

Ten derde, vergeten opruimen. Elke worktree is een echte map op je schijf. Tien per dag zonder opruimen, en je hoofdmap wordt onleesbaar. git worktree list laat zien wat er rondzwerft, git worktree prune verwijdert de dode.

De vierde valkuil: een worktree begint leeg

Een worktree bevat alleen de bestanden die Git bijhoudt. git worktree add geeft je de broncode, niet node_modules, niet de .venv, niet de .env met je lokale geheimen, niet de buildcache. Een agent die in een verse worktree start, kan de tests niet draaien, kan de devserver niet starten en zegt vaak niet waarom: npm test faalt op een ontbrekende module, de app faalt op een ontbrekende omgevingsvariabele, en de agent besteedt zijn eerste tien minuten aan loodgieterswerk in plaats van aan het ticket.

Hier zijn we zelf ingetrapt. Een gebruiker wees erop dat de worktree-optie in AgentsRoom verstopt zat in de geavanceerde opties van het agentformulier, en dat elke agent die in een worktree werd gestart geen enkele afhankelijkheid had en geen enkele test kon draaien. Allebei waar. De isolatie bestond, maar was onbruikbaar zonder een handmatige stap die niemand zich herinnerde.

Sinds versie 1.194.0 staat de optie in een blok Isolatie van het agentformulier, zichtbaar zonder iets open te klappen, en de eerste agent die in een verse worktree start, vindt die voorbereid: AgentsRoom kopieert vanuit de hoofdcheckout de genegeerde bestanden die aan een patroon voldoen (standaard alle .env*, zonder ooit iets te overschrijven, nooit naar node_modules of .git), en voert daarna het installatiecommando uit dat uit de lockfile wordt afgeleid (bun, pnpm, yarn, npm, uv, poetry, pipenv, bundle, composer) of het commando dat je in de projectinstellingen hebt ingesteld. Het commando draait in de eigen terminal van de agent, dus je ziet het, en een mislukte installatie houdt de agent niet tegen om te starten. Dit gebeurt één keer per worktree: een markering in de privé-git-map van de worktree zorgt ervoor dat de volgende start de stap overslaat.

Doe je dit met de hand, dan is het recept hetzelfde en past het in een script: .env* kopiëren, de installatie draaien, dan de agent starten. Verpak git worktree add erin, anders vergeet je het bij de derde agent.

De echte vraag: wie houdt toezicht op de vijf mappen?

Worktrees lossen bestandsbotsingen op. Ze lossen je mentale belasting niet op.

Je hebt vijf mappen, vijf agenten, vijf terminals. Welke wacht op je beoordeling? Welke is tien minuten geleden klaar terwijl je ergens anders keek? Welke is gecrasht?

Daar bereikt één worktree per agent zijn limiet als je in de terminal blijft. Je loste het technische conflict op, maar je vermenigvuldigde de vensters om in de gaten te houden.

AgentsRoom plaatst elke agent op een tegel, met zijn status en kleur, ongeacht in welke worktree hij draait. Een agent die wacht wordt rood en pingt je. Lees hoe je 3 tot 8 agenten parallel kunt draaien zonder het overzicht te verliezen voor de volledige methode bovenop worktrees.

Wat je moet onthouden

Eén agent, één worktree, één branch. Dat is de basisregel van serieus multi-agent werk.

De commando's passen in drie regels, het voordeel is onmiddellijk: je agenten stoppen met elkaar overschrijven. Voeg een weergave toe die je vertelt welke je nodig heeft, en je kunt echt vijf taken parallel uitvoeren zonder gek te worden.