Git worktree per Claude Code e Codex: guida pratica

Se fai girare più di un agente su un repository, ti servono i git worktree. Permettono a ogni agente di lavorare sul suo branch, nella sua cartella, contemporaneamente, senza pestare i piedi agli altri.

Cos'è un git worktree?

Un clone normale ha una sola working tree: una cartella, un branch in checkout. Un worktree è una cartella di lavoro aggiuntiva collegata allo stesso repository, con un altro branch in checkout. Tutti i worktree condividono un'unica storia .git, quindi i commit fatti in uno sono subito visibili negli altri, ma i file sono separati.

Per gli agenti significa che:

• Claude Code può modificare i file in ../atlas-auth su feat/auth
• Codex può modificare i file in ../atlas-search su feat/search
• Tu continui a rivedere e a far girare l'app nella cartella principale su main

Nessuno sovrascrive le modifiche di nessun altro.

Crea un worktree per ogni compito

Dalla cartella principale del repository:

# new branch + new folder next to the repo
git worktree add ../atlas-auth -b feat/auth
 
# another one, starting from a specific branch
git worktree add ../atlas-search -b feat/search origin/main
 
# see them all
git worktree list

Poi avvia un agente in ogni cartella:

cd ../atlas-auth && claude
cd ../atlas-search && codex

Dai alle cartelle dei worktree il nome del loro compito. Fra un mese atlas-auth vorrà dire qualcosa; wt2 no.

Oppure lascia che sia Claude Code a creare il worktree

Le versioni recenti di Claude Code possono creare il worktree al posto tuo:

claude --worktree feature-auth   # or: claude -w feature-auth

Il comando crea un worktree in .claude/worktrees/feature-auth/ su un nuovo branch chiamato worktree-feature-auth e avvia Claude al suo interno. Eseguilo di nuovo con un altro nome in un secondo terminale per una seconda sessione isolata. Puoi anche chiedere a Claude di «lavorare in un worktree» a sessione in corso.

Alcuni dettagli dalla documentazione sui worktree di Claude Code:

• Aggiungi .claude/worktrees/ al tuo .gitignore, così i file dei worktree non compaiono come non tracciati nel checkout principale.
• Il repository deve avere almeno un commit.
• Quando esci, Claude rimuove un worktree pulito (chiedendo prima, se ha un nome) e ti chiede se tenere un worktree che ha ancora modifiche.
• Un file .worktreeinclude elenca i file ignorati da git, come .env, da copiare in ogni nuovo worktree.

Usa claude --worktree quando Claude Code è l'unico agente sul compito. Usa il semplice git worktree add quando vuoi scegliere tu cartella e nome del branch, o eseguire Codex o un altro agente nel worktree.

Prepara ogni worktree prima di avviare l'agente

Un nuovo worktree contiene solo i file tracciati da git. Prima di affidarlo a un agente:

• Installa le dipendenze. node_modules, virtualenv e cartelle di build non sono condivisi. Esegui npm install (o l'equivalente) in ogni worktree. I package manager con uno store condiviso, come pnpm, rendono la cosa veloce.
• Copia la configurazione non tracciata. I file .env e le impostazioni locali di solito sono ignorati da git, quindi copia quello che serve per far girare l'app. Con claude --worktree, elencali invece in .worktreeinclude.
• Usa porte diverse. Due dev server non possono ascoltare entrambi sulla porta 3000. Avvia il secondo su un'altra porta, per esempio PORT=3001 npm run dev.
• Condividi le istruzioni tramite file tracciati. CLAUDE.md e AGENTS.md sono versionati in git, quindi ogni worktree li riceve in automatico.

Revisione, merge e pulizia

Quando un agente ha finito:

# in the worktree: check the work
git diff main...feat/auth
npm test
 
# in the main folder: merge
git merge feat/auth
 
# remove the worktree folder and its registration
git worktree remove ../atlas-auth
git branch -d feat/auth

Se hai cancellato a mano la cartella di un worktree, esegui git worktree prune per eliminare la voce rimasta orfana.

Errori comuni

• «Branch is already checked out». Un branch può essere in checkout in un solo worktree alla volta. Crea un nuovo branch per ogni worktree.
• Worktree dimenticati. I vecchi worktree tengono in vita i branch e occupano spazio su disco. Esegui ogni tanto git worktree list.
• Modifiche non committate al momento della rimozione. git worktree remove si rifiuta se il worktree ha modifiche. Fai prima commit o stash, oppure usa --force se vuoi davvero scartarle.
• Agenti che modificano la cartella principale. Avvia ogni agente da dentro la cartella del suo worktree, non dalla radice del repository.

I worktree in Vibe Console

Vibe Console tiene i worktree sotto gli occhi mentre gli agenti ci lavorano:

• Il pannello Worktree in Controllo del codice sorgente (⌘⇧G) elenca ogni worktree con il suo branch, segnalando quello principale e gli eventuali checkout detached.
• Trascina un worktree su un terminale per incollarne il percorso, poi avvia lì un agente con ⌘K.
• Rimuovi worktree ne fa pulizia quando hai finito, e chiede di usare Forza rimozione se ci sono ancora modifiche locali. Il worktree principale è protetto.
• La griglia mostra fino a nove terminali, così l'agente di ogni worktree può avere il suo riquadro. Vedi eseguire agenti in parallelo.

Crea i worktree con git worktree add o claude --worktree come visto sopra; entrambi compaiono subito nell'elenco.

Domande frequenti

I worktree occupano molto spazio su disco?

Solo per i file in checkout e per quello che ci installi. La storia di git è condivisa.

Meglio i worktree o cloni separati?

I worktree. Condividono un'unica storia, quindi branch e commit sono subito disponibili ovunque, e la pulizia si fa con un solo comando.

Due agenti possono condividere un worktree?

Solo se al massimo uno dei due modifica i file. Un agente revisore che si limita a leggere può condividere il worktree con l'agente che scrive il codice.

Provalo gratis per 14 giorni: scarica Vibe Console.