Git worktree in Claude Code: sessioni parallele

Informazioni pratiche su come lavorare con Ailoot sono disponibili nella documentazione.

Che cos’è un git worktree in Claude Code#

Avviare più agenti in parallelo nella stessa cartella è il problema fondamentale del vibe-coding alla velocità del 2026. Gli agenti AI scrivono codice più velocemente di quanto una persona riesca a tenere traccia di chi sta modificando cosa. Senza isolamento dei file, avviare due sessioni Claude Code in parallelo nella stessa directory finisce con una sessione che sovrascrive il lavoro dell’altra.

Git worktree risolve il problema a livello di filesystem. Hai una directory principale in cui lavori. Il comando claude --worktree feature-auth crea la cartella .claude/worktrees/feature-auth/ su un branch separato e avvia Claude Code al suo interno. I file sono isolati. Le modifiche di una sessione non sono visibili all’altra finché non le unisci esplicitamente.

La documentazione ufficiale di Anthropic lo spiega così:

Un suggerimento per verificare da sé: se ti è mai capitato un commit in cui metà dei file erano opera di qualcun altro, ti serve un worktree.

In che cosa git worktree differisce da un branch normale#

Il flusso Git standard: sei sul branch main e lanci git checkout feature-x—Git sovrascrive i file della copia di lavoro. Un npm run dev in esecuzione si interrompe perché package.json è cambiato sotto i suoi occhi. Metti da parte le modifiche non committate e aspetti che l’IDE reindicizzi i file. Torni indietro e tutto viene sovrascritto di nuovo, quindi devi mettere di nuovo da parte le modifiche e ripristinarle.

Git worktree ti offre un’altra possibilità: invece di spostare una cartella da un branch all’altro, crei una seconda cartella per un altro branch. Il comando git worktree add ../project-feature-x feature-x crea la directory ../project-feature-x/ con i file del branch feature-x. Il tuo main resta nella cartella originale e il server di sviluppo continua a funzionare.

In precedenza, la modalità worktree in Claude Code doveva essere configurata manualmente: git worktree add, poi cd, poi claude—e ripetere tutto in ogni terminale. Il flag --worktree (anche -w) fa tutte e tre le cose con un solo comando.

Avviare la prima sessione parallela: il flag --worktree#

Esempio minimo. Apri il primo terminale nella radice del progetto:

claude --worktree feature-auth

Claude Code fa tre cose:

1. Crea .claude/worktrees/feature-auth/ con uno snapshot di origin/HEAD (di solito il tuo branch predefinito).
2. Crea un nuovo branch worktree-feature-auth.
3. Avvia la sessione in questa cartella.

Apri un secondo terminale nella stessa cartella radice del repository:

claude --worktree bugfix-123

Fatto. Due sessioni Claude Code, file diversi su disco, branch Git diversi. Se nella prima scrivi il codice di autenticazione e nella seconda correggi un test non superato, fisicamente non possono intralciarsi a vicenda.

Se non vuoi digitare un nome, Claude ne inventerà uno:

claude --worktree
# → crea qualcosa come .claude/worktrees/bright-running-fox/

Un consiglio per chi è alle prime armi con Git: aggiungi .claude/worktrees/ a .gitignore. Altrimenti, quando esegui git status nella cartella principale, vedrai i contenuti di tutti i worktree come file non tracciati:

# .gitignore
.claude/worktrees/

Un errore da evitare: prima del primo avvio con --worktree in una nuova directory, entra con un normale claude (senza flag) e accetta la finestra di dialogo di attendibilità dell’area di lavoro. Altrimenti il flag non funziona e dà l’errore “trust not accepted”—anche se lo combini con -p per la modalità headless.

Dove si trovano i worktree e come trovarli#

La posizione predefinita è fissa: .claude/worktrees/<value>/ nella radice del repository. Se il tuo progetto si trova in ~/dev/my-app/, il worktree feature-auth sarà in ~/dev/my-app/.claude/worktrees/feature-auth/.

Per layout non standard (per esempio, se vuoi il worktree fuori dal repository), c’è l’hook WorktreeCreate—ne parleremo più avanti nella sezione su SVN e Mercurial.

All’interno di una sessione Claude, puoi passare a un altro worktree esistente. Basta dire nella chat: “passa a .claude/worktrees/bugfix-123” e Claude chiamerà lo strumento EnterWorktree. La cartella attuale resterà intatta: potrai tornare nello stesso modo.

Il comando Git standard mostra l’elenco di tutti i worktree, incluso quello principale e quelli creati manualmente:

git worktree list

L’output sarà simile a questo:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Copiare .env e i segreti: il file .worktreeinclude#

Quando --worktree crea una nuova cartella, questa contiene solo ciò che è stato committato in Git. .env con le chiavi API e .env.local con la configurazione locale si trovano in .gitignore, quindi non sono nel worktree. E il primo npm run dev fallisce con “MISSING DATABASE_URL.”

La soluzione artigianale è copiare .env manualmente dopo ogni --worktree. Funziona una volta, poi ci si dimentica. La soluzione di Anthropic consiste in un file .worktreeinclude nella radice del progetto che elenca i file ignorati da Git da copiare automaticamente in ogni nuovo worktree.

Crea un file .worktreeinclude nella radice del repository:

.env
.env.local
config/secrets.json

La sintassi è la stessa di .gitignore. Puoi usare pattern glob:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic fornisce una regola chiara per evitare incidenti:

In altre parole, non puoi copiare accidentalmente package.json tramite .worktreeinclude: non è in .gitignore. È sicuro inserire qualsiasi pattern nel file.

Lo stesso .worktreeinclude funziona in tre modalità: --worktree manuale, worktree automatici per i subagenti (vedi sotto) e sessioni dall’app desktop Claude.

Worktree da una pull request per la revisione del codice#

Uno scenario standard di revisione del codice: un collega ti ha inviato una PR; devi esaminare il codice, eseguire i test e lasciare un commento. Con un normale git checkout pull/1234/head, cambi di nuovo la copia di lavoro e interrompi la sessione attiva.

Con il flag --worktree, basta un comando:

claude --worktree "#1234"

Che cosa succede: Claude Code esegue git fetch origin pull/1234/head, crea un worktree in .claude/worktrees/pr-1234/ e seleziona il branch della PR. La sessione si avvia. Puoi subito chiedergli di “leggere il diff, eseguire i test e trovare errori logici”: mentre Claude lavora, la sessione principale su main continua a funzionare.

La sintassi alternativa è l’URL completo della pull request:

claude --worktree https://github.com/OWNER/REPO/pull/1234

Uso in un progetto reale: abbinare claude --worktree "#N" al tuo subagente di revisione del codice dà una revisione automatica in un minuto o due. Avvialo in background, continua a lavorare nella finestra principale e torna al risultato tramite claude agents.

Branch di base: worktree.baseRef per fresh o head#

L’impostazione predefinita è questa: ogni nuovo worktree parte da origin/HEAD. Il vantaggio è un inizio pulito che sicuramente corrisponde a ciò che vedrà CI. Lo svantaggio è che, se hai modifiche non committate o diversi commit locali oltre il remoto sul branch attuale, non saranno inclusi nel nuovo worktree.

Per avviare un worktree dal commit HEAD locale attuale, aggiungi questo a .claude/settings.json (o alle impostazioni globali):

{
  "worktree": {
    "baseRef": "head"
  }
}

Ora claude --worktree experimental-feature parte dall’attuale HEAD locale. È utile quando la funzionalità ha già commit locali non inviati. Non include modifiche tracciate ancora prive di commit. Se servono al subagente, conserva e trasferisci esplicitamente quelle necessarie, poi esamina il diff di destinazione; non confondere questo trasferimento con .worktreeinclude, dedicato ai file locali ignorati.

L’impostazione accetta esattamente due valori: "fresh" (= origin/HEAD) e "head" (= HEAD locale). Riferimenti arbitrari come "feature-branch" o un hash di commit non sono ammessi: questa è una limitazione voluta per evitare un’esplosione combinatoria di opzioni.

Isolare automaticamente i subagenti: isolation: worktree#

Quando dici a Claude “avvia tre subagenti: uno legge il database, il secondo controlla l’API e il terzo verifica i test”, per impostazione predefinita lavorano tutti nella tua copia di lavoro. Se anche solo due di loro scrivono contemporaneamente nello stesso file, si crea un conflitto. La soluzione è assegnare automaticamente a ciascuno il proprio worktree.

Metodo 1: chiedilo a voce. Scrivi a Claude nella conversazione:

Use worktrees for your agents.

Claude applicherà l’isolamento a tutti i subagenti successivi in questa sessione.

Metodo 2: impostalo esplicitamente nel subagente stesso. Nel file del subagente (per esempio, .claude/agents/code-reviewer.md), aggiungi un campo al frontmatter:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

You're a meticulous reviewer. Read the diff and look for logic errors...

Ora ogni avvio di questo subagente ottiene un worktree temporaneo in .claude/worktrees/. Se il subagente non ha scritto nulla, la cartella viene eliminata automaticamente al termine. Se ci sono modifiche non committate, Claude chiederà se conservarle o rimuoverle.

Il branch di base per i worktree dei subagenti è lo stesso di --worktree: per impostazione predefinita origin/HEAD; con worktree.baseRef: head, l’HEAD locale.

Matrice decisionale: worktree, /bg, subagente o Agent View#

Combinazioni tipiche:

• “2 funzionalità in parallelo, manualmente” — due terminali, ognuno con claude --worktree. Il caso più semplice.
• “Avvia un refactoring notturno; chiuderò l’app” — /bg + /goal con una condizione di completamento. La sessione prosegue indipendentemente dalla tua finestra.
• “Un prompt, tre indagini parallele” — tre subagenti con isolation: worktree. Ognuno nel proprio ambiente isolato.
• “Che cosa è in esecuzione adesso?” — claude agents. Una dashboard di tutte le sessioni con filtri “running”, “blocked” e “done”.

5 errori da evitare quando lavori con i worktree#

1. Hai avviato un worktree, manca .env e non funziona nulla. È il problema più comune. Un worktree è un checkout pulito senza file ignorati da Git. La soluzione è aggiungere un file .worktreeinclude con .env* e le configurazioni locali necessarie appena configuri la modalità worktree. Verifica che il file si trovi nella radice del repository, non in .claude/.

2. Vuoi passare al branch principale, esegui cd fino alla radice e perdi le modifiche non committate nel worktree. La cartella radice e il worktree sono due copie di lavoro diverse. Sei tornato indietro con cd; le modifiche nel worktree sono rimaste al loro posto, non sono sparite. Ma se ti sei confuso e hai eseguito git stash nella cartella principale, pensando di essere nel worktree, lo stash verrà creato sul branch principale, non su quello che ti aspettavi.

3. Hai avviato 5 sessioni parallele e non ricordi che cosa sta facendo ciascuna. La documentazione di Anthropic avverte esplicitamente che la maggior parte degli sviluppatori non riesce a gestire cognitivamente più di 2–3 sessioni. Un segnale di sovraccarico è aprire Agent View e non riuscire a dire subito che cosa stia facendo ogni agente. Limitati a due sessioni contemporanee. Se l’attività ne richiede di più, dovrebbe essere orchestrata tramite /goal + subagenti, non manualmente.

4. I worktree da -p (headless) non vengono ripuliti automaticamente. Il comando claude --worktree feature-x -p "do thing" non mostra una richiesta interattiva all’uscita, quindi non c’è un momento in cui Claude chieda “rimuovere il worktree?”. Questi worktree si accumulano. Rimuovili manualmente: git worktree remove .claude/worktrees/feature-x. Oppure usa uno script cron che rimuove tutto ciò che ha più di 7 giorni.

5. Finestra di dialogo di attendibilità in una nuova cartella. Se apri il repository per la prima volta e lanci subito claude --worktree, il comando fallirà. Esegui claude senza flag, accetta l’attendibilità dell’area di lavoro ed esci: poi --worktree funzionerà. È una scelta intenzionale, così Claude non ottiene accesso al progetto di qualcun altro senza il consenso dell’utente.

Pulizia: che cosa viene eliminato automaticamente#

La logica di pulizia dipende da ciò che hai fatto nel worktree e da come hai avviato la sessione. La documentazione di Anthropic elenca tre scenari:

Scenario 1: sei entrato, non hai fatto nulla e sei uscito: il worktree è stato rimosso.

Scenario 2: hai fatto del lavoro senza committarlo: all’uscita Claude chiederà “conservare o rimuovere?”. “Conservare” salva la cartella e il branch per dopo. “Rimuovere” elimina la directory insieme alle modifiche non committate e ai nuovi commit. È un’operazione distruttiva: non fare clic su “rimuovere” per abitudine.

Scenario 3: hai avviato con -p (headless) e il comando è terminato. Il worktree rimane. Rimuovilo manualmente:

git worktree remove .claude/worktrees/feature-x

Inoltre, i worktree dei subagenti e delle sessioni /bg vengono rimossi automaticamente dalla pulizia in background se hanno più di cleanupPeriodDays giorni (un’impostazione che di solito è 30 giorni per impostazione predefinita) e non contengono lavoro non salvato. La pulizia automatica non interviene sui worktree creati con --worktree: restano a tuo carico.

Alternative per SVN, Perforce e Mercurial: l’hook WorktreeCreate#

Se il repository usa Subversion o Mercurial, il flag --worktree non funzionerà direttamente. Anthropic offre un punto di estensione tramite due hook: WorktreeCreate (crea una copia isolata) e WorktreeRemove (la rimuove).

Esempio di hook SVN dalla documentazione ufficiale:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

L’hook legge da stdin il nome del worktree ({ "name": "feature-auth" }), esegue svn checkout in una directory calcolata in anticipo e stampa il percorso su stdout: Claude Code lo usa come directory di lavoro per la nuova sessione.

Un’importante avvertenza: usando un hook personalizzato, .worktreeinclude non viene usato. Se nella nuova cartella ti serve .env o un altro file ignorato da Git, copialo nello script dell’hook.

E adesso: tre meccanismi paralleli correlati#

Worktree offre isolamento dei file. /bg offre isolamento del contesto. I subagenti offrono isolamento delle attività. Ogni meccanismo risolve un problema specifico. Insieme consentono di lavorare su tre o cinque attività in parallelo senza collasso cognitivo. Questo è il bagaglio di competenze alla base del vibe-coding avanzato nel 2026.

L’argomento prosegue naturalmente con tre temi correlati: come configurare un agente autonomo usando /goal e Agent View, come creare subagenti per le tue attività e come avviare centinaia di agenti tramite Dynamic Workflows.

Apri Ailoot.