Git worktree: le fondamenta per far girare più agenti AI senza conflitti

Lanci due agenti sullo stesso repo. Uno modifica package.json, e anche l'altro. Trenta secondi dopo il tuo codice è in uno stato di cui nessuno riesce a fare il merge.

Non è un bug dei tuoi agenti. È che lavorano tutti nella stessa cartella.

La soluzione è uno strumento che Git ha da anni e che quasi nessuno usa: git worktree.

Il problema: 3 agenti, 1 repo, merge impossibile

Un normale repo Git è una cartella con un solo branch in checkout alla volta. Lavori su main, cambi branch e tutta la cartella si ribalta.

Adesso butta tre agenti autonomi dentro quella cartella. Scrivono nello stesso momento. L'agente A crea un file, l'agente B lancia git checkout per ripartire pulito e cancella il lavoro in corso di A. Ti ritrovi con file scritti a metà, un index distrutto e conflitti che ti portano via più tempo di quanto te ne sarebbe servito a scrivere il codice da solo.

Il parallelismo ti fa risparmiare tempo solo se gli agenti non si toccano a vicenda.

Cos'è un git worktree

Un worktree è una seconda cartella di lavoro collegata allo stesso repo.

Stessa history, stesso remote, ma ogni worktree ha il suo branch in checkout e i suoi file su disco. Puoi averne cinque uno accanto all'altro, ognuno su un branch diverso, senza che si intralcino.

Un solo .git, più workspace. Tutto qui.

Un worktree per agente, in pratica

Ecco come si imposta. Dal tuo 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

Hai appena creato tre cartelle, ognuna sul suo branch. Avvii un agente in ciascuna:

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

Ogni agente ha la sua cartella, il suo branch, i suoi file. L'agente auth non vedrà mai cosa fa l'agente billing. Nessuna collisione possibile.

Quando una feature è pronta, fai la review del suo branch e il merge. Poi fai pulizia:

git worktree remove ../project-auth

La cartella sparisce, il branch resta nella tua history. Pulito.

Le 3 trappole da conoscere

Prima trappola, il file centrale condiviso. Se due feature devono entrambe mettere mano allo stesso routes.ts o allo stesso schema del database, i worktree non ti salvano: il conflitto te lo prendi al momento del merge. Un agente tocca i file che condividono tutti, gli altri aspettano oppure si arrangiano.

Seconda, i branch che divergono. Mentre i tuoi agenti lavorano, main va avanti. Tre giorni dopo i tuoi branch sono indietro e fare il merge diventa una sofferenza. Fai il rebase presto e spesso, oppure tieni le sessioni corte.

Terza, la pulizia dimenticata. Ogni worktree è una cartella vera sul tuo disco. Dieci al giorno senza pulizia, e la tua cartella padre diventa illeggibile. git worktree list ti mostra cosa è rimasto in giro, git worktree prune rimuove quelli morti.

La vera domanda: chi tiene d'occhio le cinque cartelle?

I worktree risolvono le collisioni tra file. Non risolvono il tuo carico mentale.

Hai cinque cartelle, cinque agenti, cinque terminali. Quale aspetta la tua review? Quale ha finito dieci minuti fa mentre guardavi da un'altra parte? Quale è andato in crash?

È qui che un worktree per agente mostra il suo limite se rimani nel terminale. Hai risolto il conflitto tecnico, ma hai moltiplicato le finestre da tenere d'occhio.

AgentsRoom mette ogni agente su una tile, con il suo stato e il suo colore, qualunque sia il worktree in cui gira. Un agente in attesa diventa rosso e ti avvisa. Leggi come far girare da 3 a 8 agenti in parallelo senza perdere il filo per il metodo completo da costruire sopra i worktree.

Cosa portarsi a casa

Un agente, un worktree, un branch. È la regola di base del lavoro multi-agente serio.

I comandi stanno in tre righe, il vantaggio è immediato: i tuoi agenti smettono di sovrascriversi a vicenda. Aggiungi una vista che ti dice quale ha bisogno di te, e puoi davvero gestire cinque lavori in parallelo senza impazzire.