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 quarta trappola: un worktree parte vuoto

Un worktree contiene solo i file che Git traccia. git worktree add ti dà il codice sorgente, non node_modules, non il .venv, non il .env con i tuoi segreti locali, non la cache di build. Un agente che parte in un worktree nuovo non può lanciare i test, non può avviare il server di sviluppo, e spesso non dice perché: npm test fallisce per un modulo mancante, l'app fallisce per una variabile d'ambiente assente, e l'agente passa i suoi primi dieci minuti sull'idraulica invece che sul ticket.

Ci siamo cascati anche noi. Un utente ci ha fatto notare che l'opzione worktree di AgentsRoom era nascosta nelle opzioni avanzate del form dell'agente, e che qualsiasi agente avviato in un worktree non aveva nessuna dipendenza e non riusciva a lanciare un solo test. Vere entrambe le cose. L'isolamento esisteva, ma era inutilizzabile senza un passaggio manuale che nessuno ricordava.

Dalla versione 1.194.0 l'opzione si trova in un blocco Isolamento del form dell'agente, visibile senza aprire niente, e il primo agente avviato in un worktree nuovo lo trova già preparato: AgentsRoom copia dal checkout principale i file ignorati che corrispondono a un pattern (di default tutti i .env*, senza mai sovrascrivere, mai dentro node_modules o .git), poi esegue il comando di installazione rilevato dal lockfile (bun, pnpm, yarn, npm, uv, poetry, pipenv, bundle, composer) oppure quello che hai impostato nelle impostazioni del progetto. Il comando gira nel terminale dell'agente, quindi lo vedi, e un'installazione fallita non impedisce all'agente di partire. Succede una volta per worktree: un marcatore nella cartella git privata del worktree fa sì che l'avvio successivo salti questo passaggio.

Se lo fai a mano, la ricetta è la stessa e sta in uno script: copiare .env*, lanciare l'installazione, poi avviare l'agente. Avvolgi git worktree add al suo interno, altrimenti te lo dimenticherai al terzo agente.

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.