Codex CLI : le guide pratique des worktrees Git

Configurer Codex CLI au plus vite

Il vous faut Codex CLI 0.154.0, un dépôt Git local et la fonctionnalité expérimentale worktrees activée. Commencez par contrôler la version : un ancien binaire ne reconnaîtra pas le nouveau flag.

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

La commande persistante enregistre ce choix dans la configuration de Codex. Pour un essai ponctuel, ne modifiez pas la configuration et ajoutez simplement --enable worktrees à l'invocation concernée.

Vous pouvez alors ouvrir une nouvelle session isolée, lancer une tâche sans interface ou bifurquer depuis une conversation existante :

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"

Pour la bifurcation interactive, <session-id> correspond à l'identifiant de chat affiché par /status. La version 0.154.0 exige ici un identifiant explicite : codex fork --worktree --last n'est pas accepté.

Le même workflow est disponible dans l'interface du terminal. Saisissez /worktree, puis choisissez de poursuivre la conversation en cours dans une nouvelle copie de travail, d'y démarrer une conversation ou de parcourir les worktrees que Codex gère déjà pour ce dépôt.

Ce que Codex CLI crée en pratique

Un worktree géré est une seconde copie de travail rattachée au même dépôt Git. Imaginez un catalogue de bibliothèque commun à deux salles de lecture : chacune peut disposer un ensemble de pages différent, mais toutes deux se réfèrent aux mêmes commits et branches.

Codex crée cette copie à partir du HEAD validé du dépôt source, avec une HEAD détachée, puis l'associe à la nouvelle session. Une HEAD détachée pointe directement vers un commit au lieu de faire avancer une branche nommée. La copie source, elle, reste exactement où elle était.

Ce départ propre a une conséquence importante : les modifications non commitées de la copie d'origine ne suivent pas la session. Même chose pour les fichiers ignorés, comme un .env ou un dossier node_modules classique. OpenAI documente la copie via .worktreeinclude pour les worktrees locaux gérés par l'application Desktop, mais exclut explicitement ceux créés en ligne de commande. Avec le CLI, prévoyez donc d'initialiser tout ce dont la tâche a besoin.

Si vous lancez Codex depuis un sous-dossier du dépôt, la copie gérée conserve ce chemin relatif. Un départ depuis apps/web, par exemple, ouvre la session dans le dossier apps/web correspondant du nouveau worktree, à condition que ce dossier existe dans la version commitée.

Le workflow Git worktree, du lancement à l'intégration

La méthode la plus sûre tient en cinq temps : partir d'une base propre, vérifier où la session s'est ouverte, effectuer le travail, examiner les preuves, puis choisir explicitement de conserver ou d'abandonner le résultat.

1. Partez du commit réellement visé

--worktree est un commutateur booléen, pas un sélecteur de branche ou de base. Il démarre depuis le HEAD du dépôt indiqué. Placez-vous sur la branche de départ voulue et commitez les changements source nécessaires à la tâche avant le lancement. L'option -C <repo-path> permet de désigner une copie locale précise.

Ouvrez une nouvelle session lorsque la tâche se suffit à elle-même. Préférez une bifurcation si le nouvel essai doit conserver les décisions et contraintes de la conversation initiale. Celle-ci reprend alors dans un nouveau chat et une copie isolée, ce qui laisse la première tentative intacte pour les comparer.

2. Vérifiez la copie avant toute modification

Au démarrage, demandez à Codex d'exécuter pwd, git status --short et git rev-parse --short HEAD. Le répertoire courant doit être le chemin géré, le statut doit être propre et le commit doit correspondre au HEAD source attendu.

Cette vérification évite l'erreur banale qui coûte le plus cher : produire un excellent travail sur la mauvaise base.

3. Installez uniquement ce dont cette session a besoin

Un worktree isole les fichiers extraits. Il ne crée pas de conteneur, ne réserve pas de port, ne clone pas de base de données et n'installe aucune dépendance. Exécutez dans la copie gérée la commande d'installation habituelle du dépôt. Si plusieurs sessions peuvent entrer en conflit, attribuez-leur des ports, bases de données temporaires, répertoires de cache et comptes de test distincts.

C'est la limite essentielle à retenir. Deux diffs Git parfaitement propres peuvent tout de même se gêner si les deux sessions migrent la même base de développement ou tentent d'écouter sur le même port.

4. Examinez le diff et reprenez la bonne conversation

Dans la session du worktree, /review peut inspecter les changements non commités. Depuis un autre terminal, commencez par /worktree, choisissez Browse worktrees, sélectionnez la copie, puis Copy working directory. Exécutez ensuite git -C "<worktree-path>" status --short, git -C "<worktree-path>" diff --stat et git -C "<worktree-path>" diff.

N'exécutez pas codex review --worktree : la version 0.154.0 refuse cette combinaison. Lancez la review depuis la session active du worktree, ou pointez vos outils de review habituels vers le chemin copié.

Pour reprendre plus tard, saisissez /worktree, choisissez Browse worktrees, sélectionnez la copie gérée, puis Resume owner thread. N'ajoutez pas --worktree à codex resume : la reprise doit revenir dans la copie déjà liée à la session, pas en allouer une autre.

5. Préservez le changement avant de nettoyer

Si le changement doit être conservé, exécutez les tests pertinents, commitez-le dans le worktree et copiez le SHA du commit. Dans la copie d'origine, utilisez git cherry-pick <sha> pour l'appliquer à la branche courante. Faites ce cherry-pick avant de supprimer le worktree afin de donner au commit détaché une destination durable.

Si le travail mérite sa propre branche de review, exécutez git switch -c codex/<task> dans le worktree, commitez, poussez la branche et ouvrez une pull request. Git interdit qu'une même branche soit extraite simultanément dans la copie d'origine. Poussez-la donc depuis le worktree, ou supprimez celui-ci avant de l'extraire ailleurs.

Les worktrees créés par le CLI ne sont pas nettoyés automatiquement. Une fois le changement commité en lieu sûr ou délibérément abandonné, vérifiez que la copie est propre, puis lancez git worktree remove <worktree-path> depuis le dépôt source. Évitez --force. Plus tard, git worktree prune pourra retirer les références Git obsolètes, mais cette commande ne remplace pas la vérification qu'aucune session n'utilise encore la copie.

Ce que les worktrees changent au budget

La fonctionnalité native supprime une petite couche récurrente de commandes shell. Avant la version 0.154.0, l'utilisateur du CLI devait créer un chemin, créer ou détacher une branche, lancer Codex dans ce dossier, se souvenir du chat associé, puis nettoyer l'état de Git et celui de la session. Désormais, le nouveau flag crée et relie la copie en un seul lancement, tandis que /worktree fournit un navigateur adapté au dépôt et un parcours de reprise.

Pour un abonné Codex existant, cette copie n'entraîne aucun tarif distinct publié. Codex Plus coûte $20 par mois. Un espace de travail commercial qui organise les worktrees parallèles, Unstoppable, propose son offre Pro à partir de $19 par mois, Business à $29 par utilisateur et Enterprise à $49 par utilisateur. Codex couvre donc désormais la création de la copie et la reprise de session dans l'abonnement que vous utilisez déjà.

Il ne remplace pas pour autant le reste de cette catégorie d'outils payants. Tableaux de bord multi-agents, attribution des ports, préparation d'environnements partagés, agrégation des tests, suivi des pull requests, politiques d'équipe et reporting des coûts restent au-dessus de la simple copie de travail. Les sessions parallèles puisent également dans le même quota Codex. La bonne lecture financière n'est pas « développement parallèle gratuit », mais « un outil d'orchestration en moins si la seule raison de l'acheter était l'isolation ».

Pour situer cette fonctionnalité dans l'écosystème du produit, notre analyse de Codex détaille le CLI local et le workflow agentique. L'article consacré à Codex CLI 0.152.0 montre pourquoi les limites propres à chaque version comptent lorsqu'on automatise le terminal.

Sept usages des worktrees, classés par valeur

1. Les mises à niveau risquées de dépendances

Un mainteneur peut réserver un worktree à la mise à niveau d'un framework, d'un gestionnaire de paquets ou d'un outil de test. Codex modifie alors les lockfiles et la configuration, puis exécute toute la suite sans salir le développement en cours dans la copie principale. À la clé : un chantier facile à examiner et à abandonner, sans stash ni retour arrière sur des changements sans rapport.

2. Deux implémentations concurrentes d'une même fonctionnalité

Un lead technique peut bifurquer la même conversation de conception vers deux worktrees gérés, demander à une session le patch minimal et à l'autre une approche plus structurelle, puis comparer la taille des diffs, les tests et le risque de migration. Le choix repose ainsi sur des preuves, sans que la seconde tentative écrase la première.

3. Le diagnostic d'un bug en parallèle du développement

À mi-chemin d'une fonctionnalité, un ingénieur produit peut créer depuis le HEAD commité un worktree propre pour reproduire un bug de production. Codex peut instrumenter, tester et corriger le problème dans cet environnement isolé, tandis que la fonctionnalité inachevée reste intacte. Résultat : moins de stashes d'urgence et un diff de hotfix plus propre.

4. Les grands codemods et refactorings

Une équipe plateforme peut isoler un renommage massif ou une migration d'API dans sa propre copie, y lancer les outils de formatage et les tests, puis examiner la liste des fichiers touchés avant toute entrée dans la branche principale. L'intérêt tient au confinement : le bruit généré reste à l'écart jusqu'à mériter un commit.

5. Un espace isolé pour les corrections de review

L'auteur d'une pull request peut commiter la base de review, ouvrir une session Codex isolée depuis cet état et traiter les commentaires sans perturber une autre branche active en local. Il obtient une série de corrections ciblées, qu'il peut pousser depuis le worktree dès qu'elle est prête.

6. Des opérations de maintenance reproductibles

Un ingénieur build peut employer codex exec --worktree pour une tâche ciblée, par exemple mettre à jour des fichiers générés ou enquêter sur un test instable. L'exécution sans interface dispose d'une copie propre des fichiers suivis et d'une session persistante, consultable plus tard. Elle évite ainsi la contamination accidentelle par le contenu de la copie principale. En contrepartie, l'automatisation doit prendre en charge l'installation des dépendances et le nettoyage.

7. Une découverte sans risque du dépôt

Un nouveau membre de l'équipe peut laisser Codex cartographier un codebase inconnu et tenter une petite modification de documentation ou de test dans un worktree géré, avant de toucher à sa copie habituelle. Le bénéfice est autant psychologique que technique : l'exploration possède une frontière visible et une sortie facile.

Trois produits à construire autour des besoins non couverts

1. Le meilleur pari : rendre chaque worktree immédiatement opérationnel

Créez un petit outil local qui transforme toute nouvelle copie gérée en environnement de tâche exécutable et sans conflit. Il détecterait la stack du projet, lancerait l'installation de dépendances approuvée, attribuerait un port, créerait une base ou un schéma temporaire, n'exposerait que certains secrets, effectuerait un contrôle de santé et afficherait le plan de nettoyage correspondant.

La demande est large : git worktree représente environ 9,900 recherches Google mensuelles aux États-Unis, et what is a git worktree en totalise 590 de plus. La fonctionnalité native de Codex règle la création de la copie, mais pas sa préparation à l'exécution. C'est donc l'opportunité la plus solide.

La plus petite version commercialisable doit proposer un manifeste de dépôt, des commandes d'installation et de suppression, la réservation des ports, des modèles de fichiers d'environnement et une vérification d'état. Le vrai point de vigilance est la sécurité : un outil qui copie des secrets ou oriente deux agents vers la même base de données peut aggraver le risque. OpenAI pourrait aussi ajouter des hooks de cycle de vie natifs et réduire cet espace.

2. Un tableau de bord pour les sessions multi-agents

Créez un tableau de bord desktop ou terminal qui découvre les worktrees de plusieurs dépôts et outils, puis affiche la session propriétaire, la branche ou l'état détaché, les fichiers modifiés, le résultat des tests, l'usage Codex, la pull request, l'espace disque et une action sûre pour reprendre ou nettoyer.

git worktree claude code atteint environ 480 recherches mensuelles aux États-Unis, contre 10 pour l'expression exacte parallel coding agents. Ce second volume est faible, mais un comportement payant existe déjà : Unstoppable démarre à $19 par mois pour un produit qui comprend des worktrees d'agents parallèles. L'acheteur utilise déjà Codex, Claude Code et des terminaux classiques.

Un MVP peut rester en lecture seule : répertorier les worktrees Git, les rapprocher des métadonnées de sessions connues, exécuter à la demande des commandes de statut et de test, puis proposer un lien direct vers chaque agent. Le risque vient de la concurrence native. Codex 0.154.0 sait déjà parcourir ses propres worktrees gérés ; ce produit doit donc s'imposer par sa visibilité multi-agents, son suivi de l'état d'exécution et son reporting d'équipe.

3. Un garde-fou pour l'intégration et le nettoyage

Créez une barrière entre une session agentique terminée et la branche principale. Elle vérifierait que l'état Git est propre, exécuterait les tests requis, détecterait les fichiers modifiés par d'autres worktrees actifs, recommanderait l'ordre des cherry-picks et refuserait tout nettoyage destructif tant que des commits n'ont pas été intégrés.

La demande apparaît déjà dans les requêtes : git remove worktree atteint environ 390 recherches mensuelles aux États-Unis, git worktree vs branch 320 et git worktree prune 140. Toutes se concentrent au moment où un travail isolé doit rejoindre le travail partagé.

Le MVP prend la forme d'une commande Git locale accompagnée d'un petit fichier de règles. Il peut rendre service sans modifier automatiquement la moindre ligne. Le principal risque concerne la distribution : les clients Git et les fournisseurs de CI peuvent ajouter les mêmes contrôles. Un outil indépendant doit donc exceller face à plusieurs agents de développement et aux dépôts réels, rarement impeccables.

Les limites de Codex CLI à intégrer à votre décision

Choisissez les worktrees natifs lorsque le problème porte sur l'isolation des fichiers. Ne les confondez pas avec une isolation complète de l'environnement.

Cette version ne propose pas non plus d'équivalent CLI au bouton Handoff de l'application Desktop. Le rapatriement du code reste une décision Git : commiter et appliquer par cherry-pick, pousser une branche, ou abandonner puis supprimer. Cette étape explicite est saine. L'isolation n'a de valeur que si rien ne se déverse par accident dans la copie principale.

Dès lundi, choisissez une mise à jour de dépendance non critique et lancez-la avec codex --enable worktrees --worktree. Comparez le diff et les tests depuis le chemin copié, n'appliquez par cherry-pick que le commit retenu, puis supprimez le worktree. Pour construire autour de vos dépôts un workflow fiable pour des agents isolés, je peux vous aider à concevoir le système de production.