Codex CLI e worktree Git: guida pratica alle sessioni isolate

La configurazione più rapida di Codex CLI

Servono Codex CLI 0.154.0, un repository Git locale e la funzionalità sperimentale worktrees abilitata. Prima di cercare un flag che una versione precedente non riconosce, conviene controllare la versione installata.

codex --version
npm install -g @openai/codex@0.154.0
codex features enable worktrees
codex features list

Il comando persistente registra la scelta della funzionalità nella configurazione di Codex. Per provarla una sola volta senza toccare la configurazione, basta aggiungere --enable worktrees a quella specifica invocazione.

A questo punto si può avviare una nuova sessione isolata, un'attività non interattiva oppure il fork di una conversazione esistente:

codex --enable worktrees --worktree "Upgrade the test runner and run its suite"
codex exec --enable worktrees --worktree "Find the flaky test and propose the smallest fix"
codex fork --enable worktrees --worktree <session-id> "Try the lower-risk implementation"

Nel fork interattivo, <session-id> è l'ID della chat mostrato da /status. La versione 0.154.0 richiede qui un ID esplicito: codex fork --worktree --last non viene accettato.

Lo stesso flusso è disponibile nell'interfaccia del terminale. Digitando /worktree si può scegliere se proseguire la conversazione corrente in un nuovo checkout, avviarvi una nuova conversazione oppure consultare i worktree che Codex gestisce già per il repository.

Che cosa crea Codex

Un worktree gestito è un secondo checkout collegato allo stesso repository Git. Si può immaginare il repository come il catalogo di una biblioteca condiviso da due sale di lettura: in ciascuna si possono disporre pagine diverse, ma entrambe fanno riferimento agli stessi commit e branch.

Codex crea il nuovo checkout dal HEAD registrato nel repository di origine, in stato detached HEAD, quindi lo associa alla nuova sessione. Detached HEAD significa che il checkout punta direttamente a un commit anziché far avanzare un branch con nome. Il checkout di origine resta esattamente dov'era.

Questa partenza pulita ha una conseguenza importante: le modifiche non ancora salvate in un commit nel checkout originale non seguono la sessione. Lo stesso vale per i file ignorati, come avviene di solito con .env o con la directory node_modules. OpenAI documenta la copia tramite .worktreeinclude per i worktree locali gestiti da Desktop, ma chiarisce esplicitamente che il comportamento non riguarda quelli creati dalla riga di comando. Nel flusso CLI bisogna quindi predisporre ciò che serve all'attività.

Se Codex viene avviato da una directory interna al repository, il checkout gestito conserva quella posizione relativa. Avviandolo, per esempio, da apps/web, la sessione si apre nella corrispondente directory apps/web del nuovo worktree, purché sia presente nella revisione registrata nel commit.

Workflow operativo: dall'avvio al recupero delle modifiche

La procedura più sicura si articola in cinque momenti: partire da una base pulita, verificare dove ci si trova, svolgere il lavoro, controllare le evidenze e infine scegliere consapevolmente se conservare o eliminare il risultato.

1. Partire dal commit corretto

--worktree è un'opzione booleana, non un selettore del branch o della base. Il punto di partenza è il HEAD del repository indicato. Prima dell'avvio, occorre passare al branch di base desiderato e salvare in un commit tutte le modifiche di origine necessarie all'attività. Con -C <repo-path> si può indicare a Codex uno specifico checkout locale.

Una nuova sessione è adatta a un'attività autonoma. Il fork è invece preferibile quando il nuovo tentativo deve mantenere decisioni e vincoli della conversazione originale. Il fork conserva la trascrizione in una nuova chat e trasferisce il nuovo lavoro in un checkout isolato: il primo tentativo resta così intatto e disponibile per il confronto.

2. Verificare il checkout prima di modificare i file

All'inizio, è utile chiedere a Codex di eseguire pwd, git status --short e git rev-parse --short HEAD. La directory di lavoro deve corrispondere al percorso gestito, lo stato deve essere pulito e il commit deve coincidere con il HEAD di origine previsto.

Questo controllo evita l'errore banale ma più costoso: fare un ottimo lavoro partendo dalla base sbagliata.

3. Installare soltanto ciò che serve a questa sessione

Un worktree isola i file sottoposti a checkout. Non crea un container, non riserva una porta, non clona un database e non installa le dipendenze. Nel checkout gestito va eseguito il normale comando di configurazione del repository. Quando le risorse possono entrare in conflitto, ogni sessione concorrente deve disporre di porte, database temporanei, directory di cache e account di test separati.

È questo il limite principale da comprendere. Due diff Git puliti possono comunque interferire tra loro se entrambe le sessioni eseguono migrazioni sullo stesso database di sviluppo o tentano di usare la stessa porta.

4. Esaminare il diff e riprendere la conversazione giusta

All'interno della sessione nel worktree, /review può esaminare le modifiche non ancora registrate in un commit. Da un altro terminale, bisogna prima usare /worktree, scegliere Browse worktrees, selezionare il checkout e poi Copy working directory. A quel punto si possono eseguire git -C "<worktree-path>" status --short, git -C "<worktree-path>" diff --stat e git -C "<worktree-path>" diff.

Non va eseguito codex review --worktree: la versione 0.154.0 rifiuta questa combinazione di flag. La revisione va effettuata nella sessione del worktree attivo, oppure indirizzando i normali strumenti di review al percorso copiato.

Per riprendere il lavoro in seguito, si digita /worktree, si sceglie Browse worktrees, si seleziona il checkout gestito e infine Resume owner thread. Non bisogna aggiungere --worktree a codex resume: la ripresa deve riportare al checkout già associato alla sessione, non crearne un altro.

5. Conservare le modifiche prima di rimuovere il checkout

Se una modifica va conservata, occorre eseguire i test pertinenti, creare un commit nel worktree e copiarne lo SHA. Nel checkout originale, git cherry-pick <sha> porta quel commit sul branch corrente. Il cherry-pick va eseguito prima di rimuovere il worktree, così il commit detached trova una destinazione permanente.

Quando il lavoro merita un branch di revisione dedicato, nel worktree si esegue git switch -c codex/<task>, quindi si crea il commit, si esegue il push e si apre una pull request. Git non permette che lo stesso branch sia attivo contemporaneamente anche nel checkout originale. Lo si può pubblicare dal worktree, oppure rimuovere il worktree prima di aprire il branch altrove.

I worktree creati dalla CLI non vengono rimossi automaticamente. Dopo aver salvato le modifiche in un commit o aver deciso di scartarle, bisogna verificare che il checkout sia pulito ed eseguire git worktree remove <worktree-path> dal repository di origine. È meglio evitare --force. In seguito, git worktree prune può eliminare registrazioni Git obsolete, ma non sostituisce la verifica che nessuna sessione possieda ancora quel checkout.

Come cambia il costo operativo

La funzionalità nativa elimina un piccolo ma ricorrente strato di comandi shell. Prima della versione 0.154.0, chi usava la CLI doveva creare un percorso, creare o scollegare un branch, avviare Codex in quella directory, ricordare quale chat vi fosse associata e infine ripulire sia lo stato Git sia quello della sessione. Ora il nuovo flag crea e associa il checkout in un'unica operazione, mentre /worktree offre un browser che conosce il repository e un percorso per riprendere il lavoro.

Per chi ha già un abbonamento Codex, non è pubblicato alcun costo separato per il checkout. Codex Plus costa $20 al mese. Un workspace commerciale per agenti che organizza worktree paralleli, Unstoppable, propone un piano Pro a partire da $19 al mese, un piano Business a $29 per utente e un piano Enterprise a $49 per utente. Codex nativo può ora coprire, all'interno dell'abbonamento già in uso, il compito specifico di creare un checkout e riprendere la relativa sessione.

Non sostituisce però tutto il resto della categoria dei workspace a pagamento. Dashboard per più agenti, assegnazione delle porte, configurazione di ambienti condivisi, aggregazione dei test, monitoraggio delle pull request, policy di team e rendicontazione dei costi restano un livello superiore rispetto al semplice checkout. Inoltre, le sessioni parallele attingono tutte alla stessa quota di utilizzo di Codex. La lettura economica corretta non è «sviluppo parallelo gratuito», ma «uno strumento di orchestrazione in meno, se l'isolamento era l'unico motivo per acquistarlo».

Per una panoramica più ampia del prodotto che include questa funzionalità, la recensione di Codex analizza la CLI locale e il flusso di lavoro con gli agenti. Il precedente approfondimento su Codex CLI 0.152.0 mostra perché i limiti legati a una specifica release contano quando si automatizza il terminale.

Sette casi d'uso dei worktree, in ordine di valore

1. Aggiornamenti rischiosi delle dipendenze

Chi mantiene un progetto può aprire un worktree per aggiornare un framework, un package manager o un test runner, lasciare che Codex modifichi lockfile e configurazione ed eseguire l'intera suite senza sporcare il lavoro sulla funzionalità aperto nel checkout principale. Il vantaggio è un percorso di aggiornamento facile da revisionare e da scartare, senza dover ricorrere a uno stash o annullare modifiche non correlate.

2. Due implementazioni concorrenti della stessa funzionalità

Un tech lead può eseguire il fork della stessa conversazione di pianificazione in due worktree gestiti, chiedere a una sessione la patch più piccola e all'altra un approccio più strutturale, quindi confrontare dimensione del diff, test e rischio della migrazione. La scelta si basa così sulle evidenze, senza che il secondo tentativo sovrascriva il primo.

3. Analisi di un bug mentre prosegue lo sviluppo del prodotto

Chi sta sviluppando una funzionalità può avviare da HEAD un worktree pulito per riprodurre un bug in produzione. In quella sessione Codex può aggiungere strumentazione, testare e correggere il problema, mentre la funzionalità ancora incompleta resta intatta. Il risultato sono meno stash d'emergenza e un diff più pulito per l'hotfix.

4. Codemod e refactoring di grandi dimensioni

Un team di piattaforma può dedicare un checkout a un'ampia rinomina o alla migrazione di un'API, eseguire lì formatter e test e controllare l'insieme dei file modificati prima che raggiunga il branch principale. Il vantaggio è il contenimento: le modifiche generate in massa restano separate finché non meritano un commit.

5. Una sessione dedicata alle correzioni di review

L'autore di una pull request può salvare in un commit la base della revisione, avviare da quello stato una sessione Codex isolata e rispondere ai commenti senza disturbare un altro branch attivo in locale. Il risultato è una serie mirata di correzioni, pronta per essere pubblicata dal worktree quando è completa.

6. Attività di manutenzione riproducibili

Un build engineer può usare codex exec --worktree per un'attività circoscritta, come aggiornare file generati o indagare su un test instabile. L'esecuzione non interattiva dispone di un checkout pulito dei file tracciati e di una sessione persistente, che resta ispezionabile in seguito. Si riduce così il rischio di contaminazione accidentale da tutto ciò che è aperto nel working tree principale; l'automazione deve però occuparsi della configurazione delle dipendenze e della pulizia finale.

7. Esplorare un repository in sicurezza

Chi entra da poco in un team può affidare a Codex la mappatura di un codebase sconosciuto e provare una piccola modifica alla documentazione o ai test in un worktree gestito, prima di intervenire sul checkout abituale. Il beneficio è tanto psicologico quanto tecnico: l'esplorazione ha un confine visibile e una semplice via d'uscita.

Tre prodotti da costruire per colmare ciò che manca

1. La scommessa migliore: preparare i worktree all'esecuzione

Si potrebbe creare un piccolo strumento locale capace di trasformare un checkout gestito appena creato in una sessione operativa, eseguibile e priva di conflitti. Lo strumento rileverebbe lo stack del progetto, avvierebbe la procedura approvata per installare le dipendenze, assegnerebbe una porta, creerebbe un database o uno schema temporaneo, esporrebbe soltanto i secret selezionati, eseguirebbe un controllo di integrità e infine mostrerebbe il piano di pulizia corrispondente.

La domanda è ampia: git worktree registra circa 9,900 ricerche Google al mese negli Stati Uniti, mentre what is a git worktree ne raccoglie altre 590. La funzionalità nativa di Codex risolve la creazione del checkout ma non prepara l'ambiente di runtime: proprio per questo è l'opportunità più promettente.

La versione minima vendibile richiede un manifest del repository, comandi di configurazione e smantellamento, prenotazione delle porte, template per i file di ambiente e un controllo dello stato. Il vero punto critico è la sicurezza. Uno strumento che copia secret o indirizza due agenti verso lo stesso database può aumentare i rischi invece di ridurli. Inoltre, OpenAI potrebbe introdurre hook nativi per il ciclo di vita e restringere questo spazio di mercato.

2. Una dashboard per le sessioni di agenti diversi

Si potrebbe creare una dashboard desktop o da terminale che individua i worktree tra repository e strumenti differenti e mostra la sessione proprietaria, il branch o lo stato detached, i file modificati, l'esito dei test, il consumo di Codex, la pull request, lo spazio su disco e un'azione sicura per riprendere o ripulire il lavoro.

git worktree claude code genera circa 480 ricerche Google mensili negli Stati Uniti e la frase esatta parallel coding agents ne genera 10. Quest'ultima query è piccola, ma il comportamento di acquisto è visibile: Unstoppable parte da $19 al mese per un prodotto che include worktree destinati ad agenti paralleli. Il cliente è uno sviluppatore che gestisce già contemporaneamente Codex, Claude Code e normali terminali.

L'MVP può restare in sola lettura: elencare i worktree Git, associarli ai metadati noti delle sessioni, eseguire su richiesta i comandi di stato e di test e offrire collegamenti diretti a ciascun agente. Il rischio è la concorrenza delle funzioni native. Codex 0.154.0 consente già di consultare i worktree che gestisce; per distinguersi, questo prodotto deve offrire visibilità tra agenti diversi, stato del runtime e report per i team.

3. Un controllo per integrazione e pulizia

Si potrebbe creare una protezione tra la sessione conclusa di un agente e il branch principale. Verificherebbe che lo stato sia pulito, eseguirebbe i test richiesti, rileverebbe i file modificati da altri worktree attivi, suggerirebbe un ordine per i cherry-pick e impedirebbe la pulizia distruttiva quando esistono ancora commit non integrati.

La domanda emerge già dalle ricerche: git remove worktree ne raccoglie circa 390 al mese negli Stati Uniti, git worktree vs branch 320 e git worktree prune 140. Queste query si concentrano proprio sul momento in cui il lavoro isolato deve confluire in quello condiviso.

L'MVP consiste in un comando Git locale e in un piccolo file di policy. Può essere utile senza modificare automaticamente neppure una riga. Il limite è la distribuzione: client Git e fornitori CI possono aggiungere gli stessi controlli, quindi uno strumento indipendente deve offrire un supporto eccellente per più agenti di sviluppo e repository reali, con tutte le loro complessità.

I limiti che devono orientare la scelta

I worktree nativi sono adatti quando il problema è isolare i file. Non vanno confusi con un ambiente completamente isolato.

In questa release, inoltre, la CLI non offre un equivalente del pulsante Handoff dell'app Desktop. Riportare il codice nel progetto principale resta una decisione Git: creare un commit e applicare un cherry-pick, pubblicare un branch oppure scartare tutto e rimuovere il worktree. È giusto che il passaggio sia esplicito. L'isolamento è utile proprio perché nulla dovrebbe confluire per errore nel checkout principale.

La prossima mossa per lunedì: scegliere un aggiornamento non critico delle dipendenze, eseguirlo con codex --enable worktrees --worktree, confrontare diff e test dal percorso copiato del checkout, applicare con cherry-pick soltanto il commit approvato e infine rimuovere il worktree. Per progettare un flusso affidabile di agenti isolati intorno ai propri repository, posso aiutarti a costruire il sistema di produzione.