Codex worktree: een aparte werkkopie voor een tweede taak

Stel: je gebruikt Codex CLI om één module te refactoren wanneer er een tweede taak bijkomt: tests schrijven voor een andere module. Een tweede sessie in dezelfde map openen is riskant: je kunt wijzigingen van de eerste en tweede taak gemakkelijk door elkaar halen. De vlag --worktree maakt voor de tweede taak een aparte map van hetzelfde project aan en laat de eerste map ongemoeid.

Praktische informatie over parallel werken met agents: Ailoot-documentatie.

Wat --worktree aanmaakt en welke bestanden in de kopie terechtkomen#

In Git-termen is een worktree een extra werkmap die aan dezelfde repository is gekoppeld: de commitgeschiedenis wordt gedeeld, maar de bestanden op schijf vormen een eigen verzameling. In Codex CLI 0.155.1 gebruikt de vlag --worktree dit Git-mechanisme om een nieuwe agentsessie in een aparte map te starten, terwijl de map waarin de eerste taak al wordt uitgevoerd ongemoeid blijft.

De nieuwe werkkopie bevat de bestanden van de commit waarnaar HEAD van het oorspronkelijke project bij het starten verwijst — de nieuwste commit, en niet het moment waarop je voor het laatst een bestand in je editor hebt opgeslagen. Deze opdracht neemt niet-gecommitte wijzigingen en nieuwe bestanden niet mee. Opslaan in je editor is niet hetzelfde als committen in Git. Als er nog niet-gecommitte wijzigingen in de eerste map staan wanneer je de tweede taak start, blijven die alleen in die map.

Dit is geen back-up van de volledige repository en isoleert ook niet de hele computer. Het is een tweede werkmap voor hetzelfde project, met toegang tot dezelfde branch en commitgeschiedenis. Zie voor een vergelijkbaar mechanisme in een andere tool Claude Code en git worktree: parallelle taken.

Voorbereiding: versie, projectvertrouwen en een commit#

Controleer drie dingen voordat je begint. Voer de opdrachten uit vanuit de map van het oorspronkelijke project.

Controleer eerst de versie van Codex CLI. Deze instructies gelden voor versie 0.155.1; controleer voor andere versies afzonderlijk hoe de vlaggen zich gedragen:

codex --version

Ten tweede heb je een lokaal Git-project nodig waarvan HEAD naar een bestaande commit verwijst — met andere woorden: de repository moet minstens één commit bevatten. Anders is er niets om de kopie op te baseren.

Ten derde moet de bron vertrouwd zijn: als het project expliciet als niet-vertrouwd is gemarkeerd, mislukt het starten met --worktree voordat de kopie wordt gemaakt. Als je Codex CLI net aan het instellen bent, vind je de basisvoorbereiding in Codex (OpenAI): wat het is en hoe je aan de slag gaat.

Controleer vooraf de lijst met bestaande worktrees van deze repository. Je kunt die na het starten ter vergelijking gebruiken:

git worktree list

Aparte mappen helpen om taken gescheiden te houden. Voor een algemene aanpak van werken met een agent zijn de praktische informatiebronnen in de Ailoot-documentatie nuttig.

Stappen: een aparte kopie starten voor een tweede taak#

1. Schakel de experimentele functie in en start een sessie met een aparte kopie

   Voer de opdracht uit vanuit de map van het oorspronkelijke project, waar je al aan de eerste taak werkt.

   codex --enable worktrees --worktree
   

   Verwacht resultaat: Codex maakt op basis van de huidige HEAD een nieuwe werkkopie van het project en opent daarin een agentsessie. De kopie heeft de status detached HEAD, zonder gekoppelde branch met een naam. Zo werkt de vlag in versie 0.155.1.

2. Geef de worktrees opnieuw weer in een andere terminal in het oorspronkelijke project

   git worktree list
   

   Verwacht resultaat: de uitvoer bevat een extra regel met het pad van de nieuwe kopie en een marker voor detached HEAD (of een branch, als die er is). Deze lijst laat zien dat Git de kopie heeft geregistreerd, maar bevestigt niet dat de agent de taak heeft afgerond. Open de map op het vermelde pad en controleer de inhoud om zeker te weten dat de bestanden er staan.

Het resultaat controleren en je werk bewaren#

Zodra de tweede taak in de nieuwe kopie is afgerond, moet je het resultaat apart opslaan en overzetten. De opdracht --worktree voegt wijzigingen niet samen met de main-branch en zet het resultaat ook niet automatisch over. De kopie blijft in de status detached HEAD, dus een commit erin maken creëert op zichzelf geen nieuwe branch. Als je die commits wilt bewaren, koppel ze dan aan een branch of zet ze over naar het hoofdproject voordat je de map van de kopie verwijdert.

Verwijder de map van de kopie niet voordat het resultaat is bewaard. Controleren of de werkmap schoon is, vervangt het bewaren van de commits die je nodig hebt niet: er kan nog steeds geen branch aan gekoppeld zijn.

Als je tegelijkertijd aan taken in verschillende tools werkt, plan dan vooraf hoe je voorkomt dat ze elkaar in de weg zitten. Werken met twee agents tegelijk wordt behandeld in Claude Code en Codex samen.

Als het starten is onderbroken: waar je de kopie kunt vinden#

Het starten met --worktree kan om verschillende redenen mislukken:

• de functie was niet vooraf ingeschakeld en de startopdracht bevat geen --enable worktrees: Codex weigert te starten met de vlag --worktree;
• je bevindt je in de verkeerde map of er is geen commit: als de huidige map geen Git-repository is of nog geen commits bevat, is er niets om de kopie op te baseren;
• het project is expliciet als een niet-vertrouwde bron gemarkeerd: Codex weigert een sessie met --worktree te starten. Controleer eerst of je het juiste project hebt geopend. Wijzig de vertrouwensstatus niet automatisch.

Als de sessie geen verbinding kon maken met de nieuw aangemaakte kopie — bijvoorbeeld omdat het proces werd onderbroken — wordt de werkmap niet automatisch verwijderd. Controleer eerst de lijst met worktrees en controleer voordat je iets verwijdert of er nog een Codex CLI-sessie deze kopie gebruikt:

git worktree list

Open de map en sla eventuele wijzigingen die je nodig hebt op voordat je de map verwijdert. De kopie kan blijven bestaan, ook als de agentsessie niet volledig is gestart. Als de kopie bestaat, niet meer nodig is en je zeker weet dat geen enkele sessie die gebruikt, verwijder deze dan handmatig vanuit de oorspronkelijke repository met git worktree remove en geef het pad van de map op. Voeg --force niet toe: als de kopie niet-gecommitte of niet-getrackte bestanden bevat, weigert de opdracht deze te verwijderen. Controleer bij een weigering de inhoud van de map zonder de beveiliging uit te schakelen.

Controleer na het bijwerken van Codex CLI opnieuw de versie met codex --version en herhaal de controle met git worktree list: experimentele vlaggen kunnen zich per versie anders gedragen.

Meer informatie en hulpmiddelen: Ailoot.