Codex worktree: una copia di lavoro separata per una seconda attività

Per esempio, stai usando Codex CLI per rifattorizzare un modulo quando arriva una seconda attività: scrivere test per un altro modulo. Aprire una seconda sessione nella stessa cartella è rischioso: è facile confondere le modifiche della prima e della seconda attività. Il flag --worktree crea una cartella separata dello stesso progetto per la seconda attività, lasciando intatta la prima.

Risorse pratiche per lavorare con agenti in parallelo: documentazione di Ailoot.

Cosa crea --worktree e quali file vengono copiati#

Nella terminologia Git, un worktree è una cartella di lavoro aggiuntiva collegata allo stesso repository: condivide la cronologia dei commit, ma ha un proprio insieme di file su disco. In Codex CLI 0.155.1, il flag --worktree usa questo meccanismo Git per avviare una nuova sessione dell'agente in una cartella separata, lasciando intatta la cartella in cui è già in corso la prima attività.

La nuova copia di lavoro contiene i file del commit a cui punta HEAD del progetto originale al momento dell'avvio: l'ultimo commit, non l'ultima volta che hai salvato un file nell'editor. Questo comando non trasferisce le modifiche non confermate né i nuovi file. Salvare nell'editor non equivale a fare un commit in Git. Se la prima cartella contiene ancora modifiche non confermate quando avvii la seconda attività, tali modifiche rimarranno soltanto in quella cartella.

Non si tratta di una copia di backup dell'intero repository né dell'isolamento dell'intero computer. È una seconda cartella di lavoro dello stesso progetto, con accesso allo stesso branch e alla stessa cronologia dei commit. Per un meccanismo simile in un altro strumento, consulta Claude Code e git worktree: attività parallele.

Preparazione: versione, attendibilità del progetto e un commit#

Prima di iniziare, verifica tre cose. Esegui i comandi dalla cartella del progetto originale.

Per prima cosa, controlla la versione di Codex CLI. Queste istruzioni si applicano alla versione 0.155.1; per altre versioni, verifica separatamente il comportamento dei flag:

codex --version

In secondo luogo, ti serve un progetto Git locale il cui HEAD punti a un commit esistente; in altre parole, il repository deve contenere almeno un commit. Altrimenti, non c'è nulla da cui creare la copia.

In terzo luogo, la sorgente deve essere attendibile: se il progetto è contrassegnato esplicitamente come non attendibile, l'avvio con --worktree non andrà a buon fine e la copia non verrà creata. Se stai configurando Codex CLI, la preparazione di base è descritta in Codex (OpenAI): che cos'è e come iniziare.

Controlla in anticipo l'elenco delle copie di lavoro esistenti di questo repository. Potrai usarlo per un confronto dopo l'avvio:

git worktree list

Le cartelle separate aiutano a tenere distinte le attività. Per un approccio complessivo al lavoro con un agente, sono utili le risorse pratiche della documentazione di Ailoot.

Procedura: avviare una copia separata per una seconda attività#

1. Abilita la funzionalità sperimentale e avvia una sessione con una copia separata

   Esegui il comando dalla cartella del progetto originale, dove stai già lavorando alla prima attività.

   codex --enable worktrees --worktree
   

   Risultato previsto: Codex crea una nuova copia di lavoro del progetto a partire dall'HEAD corrente e apre lì una sessione dell'agente. La copia è in uno stato HEAD detached, senza alcun branch associato. È così che funziona il flag nella versione 0.155.1.

2. Elenca di nuovo le copie di lavoro in un altro terminale nel progetto originale

   git worktree list
   

   Risultato previsto: l'output contiene una riga aggiuntiva con il percorso della nuova copia e un indicatore di HEAD detached (oppure un branch, se presente). Questo elenco mostra che Git ha registrato la copia, ma non conferma che l'agente abbia completato l'attività. Per assicurarti che i file siano presenti, apri la cartella nel percorso indicato e controllane il contenuto.

Come verificare il risultato e conservare il lavoro#

Quando la seconda attività nella nuova copia è terminata, devi salvare e trasferire il risultato separatamente. Il comando --worktree non unisce automaticamente le modifiche nel branch principale né trasferisce il risultato. La copia rimane in uno stato HEAD detached, quindi fare un commit al suo interno non crea di per sé un nuovo branch. Se devi conservare quei commit, collegali a un branch oppure trasferiscili nel progetto principale prima di eliminare la cartella della copia.

Non eliminare la cartella della copia prima di aver conservato il risultato. Verificare che la cartella di lavoro sia pulita non sostituisce la conservazione dei commit necessari: potrebbero non avere ancora un branch associato.

Se stai lavorando contemporaneamente su attività in strumenti diversi, pianifica in anticipo come evitare che interferiscano tra loro. Lavorare con due agenti insieme è spiegato in Claude Code e Codex insieme.

Se l'avvio è stato interrotto: dove trovare la copia#

L'avvio con --worktree può non riuscire per diversi motivi:

• la funzionalità non era stata abilitata in precedenza e il comando di avvio non include --enable worktrees: Codex si rifiuterà di avviarsi con il flag --worktree;
• ti trovi nella cartella sbagliata oppure non c'è alcun commit: se la cartella corrente non è un repository Git o non contiene ancora commit, non c'è nulla da cui creare la copia;
• il progetto è contrassegnato esplicitamente come sorgente non attendibile: Codex si rifiuterà di avviare una sessione con --worktree. Per prima cosa, assicurati di aver aperto il progetto corretto. Non modificare automaticamente il suo stato di attendibilità.

Se la sessione non è riuscita a collegarsi alla copia appena creata, per esempio perché il processo è stato interrotto, la cartella di lavoro non viene eliminata automaticamente. Per prima cosa, controlla l'elenco delle copie di lavoro e, prima di eliminare qualsiasi cosa, assicurati che nessuna sessione di Codex CLI stia ancora usando questa copia:

git worktree list

Apri la cartella e salva le modifiche che ti servono prima di eliminarla. La copia potrebbe rimanere anche se la sessione dell'agente non è riuscita ad avviarsi. Se la copia esiste, non serve più e hai la certezza che nessuna sessione la stia usando, rimuovila manualmente dal repository originale con git worktree remove, specificando il percorso della cartella. Non aggiungere --force: se la copia contiene file non confermati o non tracciati, il comando si rifiuterà di eliminarla. Se si rifiuta, controlla il contenuto della cartella senza disattivare la protezione.

Quando aggiorni Codex CLI, controlla di nuovo codex --version e ripeti la verifica con git worktree list: i flag sperimentali possono comportarsi diversamente da una versione all'altra.

Altre risorse e strumenti: Ailoot.