Guida pratica a Codex Worktree: sviluppare più attività IA in parallelo senza sporcare il repository

Nello stesso repository stanno girando tre attività: fix/auth-expired-session, test/payment-webhook e docs/setup-node20. Il git status del main checkout è diventato un miscuglio di modifiche non correlate: la correzione del bug di login, file fixture per i test e una nota nel README su Node 20. Tutte e tre le categorie di modifica vivono nello stesso checkout, e non è più chiaro quale parte si possa committare da sola e quale possa influenzare le altre.

Non è un problema astratto di parallelismo. È la conseguenza concreta di un checkout Git sporco. La modalità Worktree di Codex app divide le attività in directory e branch separati, così ogni linea di lavoro ha un diff che puoi revieware, mergiare o ripristinare.

Local / Worktree / Cloud: come scegliere la modalità giusta

Codex app supporta tre modalità di esecuzione. Local e Worktree girano entrambi sul tuo computer. La documentazione ufficiale lo dice esplicitamente: “Both Local and Worktree threads will run on your computer”. Cloud invece gira in un ambiente remoto.

La modalità Worktree è adatta ad attività indipendenti in parallelo o a esperimenti. Ogni thread ha la propria directory e il proprio branch, quindi il main checkout non viene toccato. Local è semplice, ma quando più attività si mescolano diventa difficile separare i commit. Cloud esce completamente dal tuo computer ed è adatto a CI/CD e build remoti.

La regola è semplice: Local per una singola attività, Worktree per lavoro locale parallelo o sperimentale, Cloud per lavoro remoto.

La modalità Worktree di Codex app nel dettaglio

Creazione del Worktree e Handoff

Il flusso per creare un Worktree thread in Codex app è:

1. Creare un nuovo thread
2. Scegliere la modalità Worktree (il nome esatto nell’UI può cambiare dopo il 18/06/2026)
3. Scegliere un branch di partenza oppure lavorare di default su detached HEAD
4. Inviare il primo prompt
5. Codex inizia a lavorare in una directory isolata

Per impostazione predefinita, Codex lavora su detached HEAD. Così può continuare dentro il worktree e creare un branch quando vuoi conservare il risultato. Handoff serve a spostare thread e codice tra Local e Worktree.

Scenari di Handoff:

Da Worktree a Local: quando l’attività è finita, se sei ancora su detached HEAD crea prima un branch nel worktree. Poi usa Handoff per tornare a Local e infine fai merge o crea una PR.

Da Local a Worktree: quando vuoi spostare lavoro incompleto in un ambiente isolato, evitando di sporcare il main checkout.

Handoff non è solo un cambio di directory. Porta con sé anche il thread context corrente, la cronologia dei prompt e le modifiche non completate.

Caratteristiche dei Codex-managed worktree

I Codex-managed worktree hanno alcuni comportamenti particolari:

Posizione predefinita: $CODEX_HOME/worktrees

Numero mantenuto di default: 15 worktree (secondo la documentazione del 18/06/2026); quelli più vecchi possono essere puliti automaticamente

Permanent worktree: un worktree creato manualmente non viene eliminato automaticamente

Limite sui branch: Git non consente di fare checkout dello stesso branch in più worktree contemporaneamente; il tentativo genera errore

Eredità delle regole: AGENTS.override.md viene copiato automaticamente nel worktree, mantenendo coerenti le regole del progetto

In pratica: il numero di worktree è limitato, quelli vecchi possono essere ripuliti, lo stesso branch non può essere usato in parallelo e le regole del progetto vengono ereditate.

.worktreeinclude risolve il problema dei file ignorati

Per impostazione predefinita, i worktree ereditano solo i Git tracked files. I file in .gitignore non vengono spostati automaticamente durante Handoff. Mancano spesso .env, .env.local, cache delle dipendenze e file di configurazione locale.

La soluzione è creare un file .worktreeinclude nella root del progetto e indicare i file ignorati da copiare. Esempio:

.env
.env.local
node_modules/.cache

In questo modo, i file ignorati elencati lì possono essere copiati nel worktree durante Handoff.

KiloClaw - OpenClaw gestito per enterprise: orchestrazione agenti IA e routing intelligente

Inizia →Pubbl.

Setup scripts: far girare il progetto dentro un worktree

Un worktree vive in una directory diversa, quindi può non avere dipendenze o file mai check in. I setup scripts vengono eseguiti quando si crea un nuovo worktree o inizia un nuovo thread, così l’ambiente diventa utilizzabile.

Passaggi di configurazione:

1. Configurare setup steps in Local environments dentro Codex app
2. Creare una directory .codex per i file di configurazione
3. Scrivere script specifici per piattaforma

Esempio per un progetto Node.js:

# .codex/setup.sh
npm install
npm run build

Esempio per un progetto Python:

# .codex/setup.sh
pip install -r requirements.txt
python manage.py migrate

I setup scripts girano per ogni nuovo worktree e riducono l’installazione manuale delle dipendenze. Attenzione: UI di configurazione e formato dei file possono cambiare dopo il 18/06/2026, quindi controlla la documentazione aggiornata.

Anche senza Codex app, Plain Git worktree isola il lavoro

Se preferisci CLI o terminale, puoi creare directory isolate direttamente con Git worktree e poi avviare Codex dentro ciascuna directory. Non ti serve la gestione di Codex app, ma devi amministrare tutto manualmente.

Comandi Git worktree comuni:

# Crea un nuovo worktree e branch, nello stile del caso d'uso ufficiale
git worktree add ../analysis-highway-eda -b analysis/highway-eda

# Crea un nuovo worktree basato su un branch esistente
git worktree add ../task-b existing-branch

# Elenca tutti i worktree
git worktree list

# Rimuovi un worktree
git worktree remove ../task-a

# Pulisci metadati worktree obsoleti
git worktree prune

Confronto tra Codex-managed e Plain Git:

Plain Git worktree è adatto a chi preferisce la CLI, ma devi gestire da solo installazione delle dipendenze, configurazione dell’ambiente e pulizia. I Codex-managed worktree automatizzano una parte maggiore del lavoro.

Le Automations in background devono usare worktree?

In un repository Git, una automation può girare nel local project oppure in un dedicated background worktree. La scelta dipende dal tipo di attività e dal controllo del rischio.

Logica di scelta:

Local è adatto ad attività singole e test temporanei. Modifica direttamente il main checkout, quindi può sporcare lavoro incompleto. Se stai modificando un file, una background automation potrebbe modificare lo stesso file.

Worktree è adatto ad attività ripetute o pianificate. Isola automation changes da unfinished local work. L’automation gira in una directory indipendente e non tocca il main checkout.

Note di rischio:

Automations usa default sandbox settings, che possono cambiare dopo il 18/06/2026

Con full access, le background automations sono più rischiose, quindi dovrebbero usare worktree

Non far girare attività ripetute in background direttamente in Local

Regola pratica: un’attività temporanea singola può usare Local; attività ripetute e lavoro in background con full access dovrebbero usare Worktree.

Quali attività sono adatte al parallelo e quali devono restare seriali

I casi d’uso ufficiali suggeriscono di separare esplorazioni diverse in worktree differenti. Nella pratica, devi comunque valutare conflitti di file e dipendenze tra attività.

Tabella di decisione per attività parallele:

Regole per il parallelo:

Inizia con due piccole attività indipendenti, non con cinque o sei.

Mantieni il numero di attività intorno a 3-4 per ridurre il costo di review.

Ogni attività deve avere un criterio di verifica chiaro.

Non esagerare con il parallelo. Più attività parallele significano più costo di review e più rischio di merge conflict.

Template per la scheda attività: chiarire cosa deve fare ogni worktree

Prima di iniziare un worktree, conviene descrivere bene l’attività. Così review e tracciamento diventano più semplici.

Esempio di scheda attività:

Goal: "Correggere il bug session expired nel modulo auth"
Context:
  - "La sessione scade dopo 30 minuti, ma il frontend non mostra alcun avviso"
  - "File rilevanti: src/auth/session.js, src/components/AuthProvider.jsx"
Constraints:
  - "Non modificare lo schema del database"
  - "Non introdurre nuove dipendenze"
Done when:
  - "Il frontend mostra un avviso quando la sessione scade"
  - "npm test passa"
  - "Il flusso di login è testato manualmente"

Branch/Worktree: "fix/auth-expired-session"
Comando di verifica: "npm test && npm run lint"

Cosa compilare:

Goal: descrivi l’obiettivo in una frase

Context: fornisci contesto su file, modulo e scenario

Alibaba Cloud - Scelta top per sviluppatori, 15% di sconto esclusivo su Lighthouse

Ottieni -15% →Pubbl.

Constraints: definisci i limiti, compreso cosa non cambiare

Done when: elenca criteri di completamento verificabili

Branch/Worktree: usa un nome chiaro, come task-type/module-description

Comando di verifica: indica un comando concreto ed eseguibile

Così ogni worktree ha confini chiari. Durante la review, confronta il risultato con Done when.

Coda di merge: review, test e merge uno alla volta

Quando le attività parallele sono finite, non riversare tutto su main in una volta sola. Ordinale per rischio, poi reviewa, testa e fai merge una alla volta.

Passaggi della coda di merge:

1. Ordinare i worktree per rischio, partendo dal più basso
2. Per il primo worktree:
   • Eseguire il comando di verifica: test, lint
   • Controllare il diff e confermare il perimetro delle modifiche
   • Creare un branch se è ancora su detached HEAD
   • Revieware il diff seguendo le tue regole di PR review
3. Fare merge in Local o creare una PR:
   • Merge locale: Handoff di ritorno a Local, poi merge
   • Merge via PR: creare una PR e aspettare CI e review
4. Ripetere gli stessi passaggi per il worktree successivo
5. Quando tutte le attività sono complete, fare merge nel branch main

Checklist di verifica:

I comandi di verifica passano: test e lint

Controllo diff: il perimetro delle modifiche corrisponde all’attività

Review guidelines: nessun file sensibile, nessun secret hard-coded

CI verde, se disponibile

Flusso di test manuale completato

Note di rischio:

Non dare per scontato che i risultati di più worktree vengano mergiati automaticamente

Se più attività modificano lo stesso file, risolvi i conflitti manualmente

Mantieni review umana e test nel processo

Il punto della coda di merge è rendere il diff di ogni linea di lavoro reviewabile e reversibile, non inviare tutte le modifiche insieme.

Checklist di troubleshooting

Errore "branch already used by worktree"

Causa: il branch è già usato da un altro worktree

Soluzione:

Usa git worktree list per vedere quali branch sono occupati

Scegli un altro branch oppure rimuovi il worktree che usa quel branch

Il codice non gira dentro il worktree

Causa: mancano dipendenze o file di configurazione

Passaggi di diagnosi:

Controlla se .env e .env.local esistono; potrebbero non essere stati copiati

Controlla se le dipendenze sono installate, come node_modules o venv

Controlla se i file di configurazione sono completi

Soluzione:

Railway - Piattaforma di deploy moderna, senza operazioni complesse, online in pochi minuti

Inizia ora →Pubbl.

Configura .worktreeinclude per copiare ignored files

Configura Setup scripts per installare automaticamente le dipendenze

Lo spazio su disco dei worktree cresce troppo

Causa: automations frequenti creano molti worktree

Soluzione:

Archivia gli automation runs che non ti servono più

Esegui manualmente git worktree prune per pulire worktree obsoleti

Controlla l’impostazione di retention dei worktree in Codex app, che può cambiare dopo il 18/06/2026

Il worktree creato dall’agent non è sincronizzato con UI/thread context

Causa: quando l’agent crea un worktree automaticamente, può aggirare l’App UI

Soluzione:

Usa git worktree list per ispezionare tutti i worktree

Controlla manualmente nell’app il legame tra thread e worktree

Evita di far creare worktree automaticamente all’agent; creali dalla App UI

L’abitudine di troubleshooting più utile è controllare prima lo stato dei worktree con git worktree list, poi agire in base al tipo di errore.

Costo: le attività parallele consumano quota più in fretta

Le attività parallele tendono a consumare più turn o quota. Ogni worktree è una session indipendente, e Codex contabilizza ogni session separatamente.

Regole di costo:

Mantieni le attività parallele intorno a 3-4.

Inizia con due piccole attività indipendenti per ridurre il costo di review.

Dai a ogni attività un criterio di verifica chiaro, così eviti iterazioni infinite.

Per prezzi, quota e dettagli dei plan, rimanda a un futuro articolo su Cost & Quota. Questa pagina non ripete numeri non verificati.

Prossimi passi e letture correlate

Articoli precedenti:

Scelta dell’ingresso in Codex: breve introduzione alle modalità Local / Worktree / Cloud

Regole di progetto AGENTS.md: come ogni worktree eredita lo stesso set di regole