Codex worktree : une copie de travail séparée pour une deuxième tâche

Par exemple, vous utilisez Codex CLI pour refactoriser un module lorsqu’une deuxième tâche se présente : écrire des tests pour un autre module. Ouvrir une deuxième session dans le même dossier est risqué : il est facile de mélanger les modifications des première et deuxième tâches. L’option --worktree crée un dossier séparé pour le même projet pour la deuxième tâche, en laissant le premier intact.

Ressources pratiques sur le travail avec des agents en parallèle : documentation Ailoot.

Que crée un worktree Codex et quels fichiers contient-il ?#

Dans la terminologie Git, un worktree est un dossier de travail supplémentaire lié au même dépôt : il partage l’historique des commits, mais possède son propre ensemble de fichiers sur le disque. Dans Codex CLI 0.155.1, l’option --worktree utilise ce mécanisme Git pour démarrer une nouvelle session d’agent dans un dossier séparé, en laissant intact le dossier où la première tâche est déjà en cours.

La nouvelle copie de travail contient les fichiers du commit vers lequel pointe le HEAD du projet d’origine au lancement — le dernier commit, et non la dernière fois que vous avez enregistré un fichier dans votre éditeur. Cette commande ne transfère ni les modifications non validées ni les nouveaux fichiers. Enregistrer dans votre éditeur n’est pas la même chose que valider dans Git. Si le premier dossier contient encore des modifications non validées lorsque vous lancez la deuxième tâche, celles-ci resteront uniquement dans ce dossier.

Il ne s’agit ni d’une sauvegarde de l’ensemble du dépôt ni d’une isolation de tout l’ordinateur. C’est un deuxième dossier de travail pour le même projet, avec accès à la même branche et au même historique des commits. Pour un mécanisme similaire dans un autre outil, consultez Claude Code et git worktree : tâches en parallèle.

Préparation : version, confiance accordée au projet et commit#

Vérifiez trois éléments avant de commencer. Exécutez les commandes depuis le dossier du projet d’origine.

Tout d’abord, vérifiez la version de Codex CLI. Ces instructions concernent la version 0.155.1 ; pour les autres versions, vérifiez séparément le comportement des options :

codex --version

Deuxièmement, vous avez besoin d’un projet Git local dont le HEAD pointe vers un commit existant — autrement dit, le dépôt doit contenir au moins un commit. Sinon, il n’y a rien à partir de quoi créer la copie.

Troisièmement, la source doit être considérée comme fiable : si le projet est explicitement marqué comme non fiable, le démarrage avec --worktree échouera avant la création de la copie. Si vous êtes en train de configurer Codex CLI, les préparatifs de base sont présentés dans Codex (OpenAI) : ce que c’est et comment commencer.

Vérifiez au préalable la liste des copies de travail existantes de ce dépôt. Vous pourrez la comparer après le lancement :

git worktree list

Des dossiers séparés aident à garder les tâches distinctes. Pour une approche générale du travail avec un agent, les ressources pratiques de la documentation Ailoot sont utiles.

Étapes : démarrer une copie séparée pour une deuxième tâche#

1. Activer la fonctionnalité expérimentale et démarrer une session avec une copie séparée

   Exécutez la commande depuis le dossier du projet d’origine, où vous travaillez déjà sur la première tâche.

   codex --enable worktrees --worktree
   

   Résultat attendu : Codex crée une nouvelle copie de travail du projet à partir du HEAD actuel et y ouvre une session d’agent. La copie se trouve dans un état HEAD détaché, sans branche nommée associée. C’est ainsi que fonctionne l’option dans la version 0.155.1.

2. Répertorier à nouveau les copies de travail dans un autre terminal du projet d’origine

   git worktree list
   

   Résultat attendu : la sortie contient une ligne supplémentaire avec le chemin de la nouvelle copie et une indication de HEAD détaché (ou une branche, le cas échéant). Cette liste montre que Git a enregistré la copie, mais elle ne confirme pas que l’agent a terminé la tâche. Pour vérifier que les fichiers sont là, ouvrez le dossier indiqué et examinez son contenu.

Vérifier le résultat et préserver votre travail#

Une fois la deuxième tâche terminée dans la nouvelle copie, vous devez enregistrer et transférer le résultat séparément. La commande --worktree ne fusionne pas les modifications dans la branche principale et ne transfère pas automatiquement le résultat. La copie reste dans un état HEAD détaché ; par conséquent, y créer un commit ne crée pas à lui seul une nouvelle branche. Si vous devez préserver ces commits, rattachez-les à une branche ou transférez-les dans le projet principal avant de supprimer le dossier de la copie.

Ne supprimez pas le dossier de la copie avant d’avoir préservé le résultat. Vérifier que le dossier de travail est propre ne remplace pas la préservation des commits dont vous avez besoin : ils peuvent ne toujours être associés à aucune branche.

Si vous travaillez en même temps sur des tâches dans différents outils, planifiez à l’avance la façon d’éviter qu’elles interfèrent les unes avec les autres. Le travail avec deux agents ensemble est expliqué dans Claude Code et Codex ensemble.

Si le démarrage a été interrompu : où trouver la copie#

Le démarrage avec --worktree peut échouer pour plusieurs raisons :

• la fonctionnalité n’a pas été activée au préalable et la commande de lancement ne contient pas --enable worktrees : Codex refusera de démarrer avec l’option --worktree ;
• vous vous trouvez dans le mauvais dossier ou il n’y a aucun commit : si le dossier actuel n’est pas un dépôt Git ou ne contient encore aucun commit, il n’y a rien à partir de quoi créer la copie ;
• le projet est explicitement marqué comme une source non fiable : Codex refusera de démarrer une session avec --worktree. Vérifiez d’abord que vous avez ouvert le bon projet. Ne modifiez pas automatiquement son statut de confiance.

Si la session n’a pas réussi à se rattacher à la copie qui venait d’être créée — par exemple parce que le processus a été interrompu — le dossier de travail n’est pas supprimé automatiquement. Vérifiez d’abord la liste des copies de travail et, avant toute suppression, assurez-vous qu’aucune session Codex CLI n’utilise encore cette copie :

git worktree list

Ouvrez le dossier et enregistrez toutes les modifications dont vous avez besoin avant de le supprimer. La copie peut subsister même si la session de l’agent n’a pas fini de démarrer. Si la copie existe, n’est plus nécessaire et n’est certainement utilisée par aucune session, supprimez-la manuellement avec git worktree remove depuis le dépôt d’origine, en indiquant le chemin du dossier. N’ajoutez pas --force : si la copie contient des fichiers non validés ou non suivis, la commande refusera de la supprimer. En cas de refus, vérifiez le contenu du dossier sans désactiver la protection.

Lors de la mise à jour de Codex CLI, vérifiez à nouveau codex --version et répétez la vérification avec git worktree list : les options expérimentales peuvent se comporter différemment selon les versions.

Plus de ressources et d’outils : Ailoot.