Worktrees Codex : des Git worktrees gérés, pas à pas
Active la fonction worktrees, lance un chat dans un Git worktree géré, transforme le résultat en branche avec Work here, et lance codex --worktree directement depuis le terminal — 10 étapes tirées d’un screencast propre.
TL;DR
- Un Git worktree est un second checkout du même dépôt — chaque worktree a ses propres fichiers mais partage le dossier .git, donc des chats Codex parallèles ne s’écrasent jamais mutuellement.
- Les worktrees sont derrière un feature flag : lance codex features enable worktrees dans un terminal, redémarre l’application, et l’option New local worktree apparaît dans le composer.
- Un worktree terminé devient une branche en deux clics — Create branch la nomme codex/your-branch, puis la feuille de commit pousse et tu ouvres la PR sans quitter le worktree.
- Les worktrees gérés vivent dans $CODEX_HOME/worktrees en dossiers à nom de hachage. Codex garde les 15 plus récents, sauve un snapshot avant nettoyage et peut le restaurer depuis le chat. Les outils de création/liste sont arrivés avec Codex 0.162.0.
Codex Worktrees: The Best Feature Most Developers Ignore
Chaîne :Software Engineer Meets AI4:56
Worktrees — official Codex documentation
Docs :developers.openai.com/codex
Les images viennent d’un screencast propre ; les commandes et libellés d’interface ont été recoupés avec la documentation officielle des worktrees Codex. Les outils de worktree géré sont arrivés dans Codex 0.162.0 (octobre 2026) : "Add tools for creating and listing managed Git worktrees from trusted local projects when the worktrees feature is enabled."
La vidéo demeure la propriété de son créateur et est liée pour attribution. Les noms de produits et éléments d’interface appartiennent à OpenAI.
Comment fonctionnent les worktrees Codex, étape par étape
Activer les worktrees et en démarrer un
- 1
Sache ce qu’est un worktree avant d’activer quoi que ce soit
Un Git worktree est un second checkout complet de ton dépôt dans son propre dossier — chaque worktree a sa copie de chaque fichier, mais tous partagent les mêmes métadonnées .git. C’est pourquoi plusieurs chats Codex parallèles peuvent chacun éditer leur dossier sans trébucher sur les changements non committés des autres. Les worktrees sont une fonction Git tout ce qu’il y a de plus banale ; Codex se contente d’automatiser les corvées autour.
La vidéo s’ouvre sur la définition en une phrase : plusieurs branches d’un même dépôt checkoutées dans des dossiers différents en même temps.Regarder à 0:28 - 2
Active la fonction worktrees une fois pour de bon
Les worktrees sont encore sous férule dans Codex, donc la première étape se passe dans un terminal. Comme montré dans la vidéo, le présentateur ouvre le terminal intégré de l’application et lance codex features enable worktrees, ce qui bascule le flag dans config.toml — puis redémarre l’application. Après le redémarrage, l’option New local worktree apparaît dans le composer.
L’application Codex avec un panneau terminal ouvert sous le composer, là où la commande d’activation tourne avant le redémarrage.Regarder à 1:58 - 3
Lance un chat sur un New local worktree
Dans un nouveau chat, les puces du composer se lisent : nom du projet, New local worktree, No environment, main — le mode worktree et la branche de départ. Garde New local worktree sélectionné et main comme branche de départ, tape ta tâche (ici, "change the background color to be blue"), et envoie.
Le composer avec New local worktree et main sélectionnés pendant la frappe du prompt.Regarder à 3:00 - 4
Laisse l’agent travailler dans son worktree
Codex répond "Worktree created" et se met au travail dans la copie isolée — le fil le montre en train de lancer npm run type-check && git diff --check pendant que tu continues d’utiliser l’application pour d’autres chats. Ton checkout principal reste intact, et le compteur Changes (+2 -2 dans la vidéo) suit ce que l’agent édite dans le worktree.
L’en-tête du fil affiche Worktree created pendant que l’agent lance type-check et diff dans le worktree.Regarder à 3:17
Transformer le worktree en branche puis en PR
- 5
Trouve où Codex garde les worktrees
Les worktrees gérés ne sont pas déposés à côté de ton projet. La doc officielle les place dans $CODEX_HOME/worktrees, et la vidéo le confirme : après un cd dans .codex/worktrees, ls imprime un dossier à nom de hachage par worktree (09bd, 09ec, 7b3a, d021, dd4e). Tu peux déplacer la racine dans Settings > Worktrees via le réglage Worktree root.
Un terminal dans .codex/worktrees listant cinq dossiers worktree à nom de hachage.Regarder à 3:41 - 6
Ouvre le menu du fil et crée une branche
Un nouveau worktree démarre détaché — Codex le crée sans branche attachée. Pour garder le travail, ouvre le menu Environment du fil : Changes (+2 -2), Worktree, Create branch, Commit or push et Create pull request. Create branch est l’action qui transforme ce dossier en une vraie branche nommée.
Le menu Environment du fil avec Changes, Worktree, Create branch, Commit or push et Create pull request.Regarder à 3:25 - 7
Confirme la branche dans le dialogue Work here
Create branch ouvre le dialogue Work here : "Create a branch to commit changes, push, and create a PR from this worktree." Le champ Branch name est prérempli avec le préfixe codex/ — codex/change-background-color dans la vidéo — clique sur Create et la branche s’attache au worktree. Git n’autorise une branche à être checkoutée que dans un seul worktree à la fois, et c’est exactement pour cela que Codex suit cette paire pour toi.
Le dialogue Work here avec le nom de branche prérempli codex/change-background-color et le bouton Create.Regarder à 3:52 - 8
Commite et pousse depuis le worktree
De retour dans le fil, Commit or push ouvre une feuille de commit sur la branche codex/change-background-color : tape un message, garde Include unstaged changes coché (+2 -2), et choisis Commit, Commit and push ou Push. La vidéo crée ensuite la pull request vers main — tout le flux n’a jamais quitté le dossier du worktree.
Feuille de commit sur la branche codex/change-background-color avec Include unstaged changes et l’option Commit and push.Regarder à 4:04
La voie CLI et les règles qui mordent
- 9
Sans l’application : lance un worktree depuis le CLI
La même fonction marche en headless. Dans la vidéo, le présentateur tape codex --worktree "Implement the new feature" à l’invite zsh dans le dépôt — Codex crée un worktree géré pour ce chat et y exécute la tâche, exactement comme l’application. Ces outils de création et de liste sont arrivés dans Codex 0.162.0 pour les projets locaux de confiance.
Terminal sur la branche main du dépôt, lançant codex --worktree "Implement the new feature".Regarder à 4:38 - 10
Connais les règles de nettoyage et la limite d’une branche
Codex garde tes 15 worktrees gérés les plus récents et élague les plus vieux à mesure que de nouveaux arrivent — jamais un chat épinglé, un chat en cours ou un worktree permanent, et toujours après avoir sauvé un snapshot restaurable depuis le chat. Deux bords durs de la doc : une branche ne peut être checkoutée que dans un seul worktree à la fois (utilise Handoff plutôt qu’un second checkout), et les fichiers ignorés comme .env ne voyagent pas vers les worktrees tant que tu ne les listes pas dans un fichier .worktreeinclude.
Documentation officielle Worktrees : ce qu’est un worktree, la terminologie et le comportement de nettoyage.Regarder à 4:47
Worktree Codex qui ne fonctionne pas ? Vérifie ceci d’abord
La plupart des échecs de worktree relèvent de la configuration, pas de Git. La vidéo et la doc officielle pointent la même courte liste — parcours-la de haut en bas avant de toucher à .git à la main.
- 1Feature flag désactivé. Les worktrees sont sous férule : lance codex features enable worktrees dans un terminal, puis redémarre complètement l’application Codex. Une option New local worktree absente du composer signifie presque toujours que cette étape — ou le redémarrage — n’a pas eu lieu.
- 2Le projet n’est pas un dépôt Git. Les worktrees ne marchent que dans les projets faisant partie d’un dépôt Git, et les notes de 0.162.0 restreignent les outils aux "trusted local projects" — un simple dossier ou un nouveau dépôt non fiable ne proposera pas l’option worktree.
- 3La branche de départ est déjà checkoutée ailleurs. Git n’autorise qu’un worktree par branche, donc choisir une branche occupée échoue avec fatal: 'branch' is already used by worktree at .... Part de main ou d’une autre branche libre, ou utilise Handoff pour déplacer le chat.
- 4Tes fichiers d’env n’apparaissent pas dans le worktree. Git ne suit pas .env et compagnie, donc ils ne sont pas copiés. Liste-les dans un fichier .worktreeinclude à la racine du dépôt (un chemin par ligne) et Codex les copie dans les nouveaux worktrees.
- 5Une application périmée. La vidéo s’ouvre sur "make sure you update yours to the latest version" — les outils de worktree géré n’existent que dans les builds récents (0.162.0 ou plus pour les outils CLI create/list). Mets à jour, active le flag, redémarre, et réessaie.
Si un worktree a déjà disparu mais que le travail comptait, ouvre d’abord son chat — Codex sauve un snapshot avant de nettoyer un worktree et peut le restaurer. Et si tout ce modèle te semble lourd, le bon vieux git worktree add marche toujours : Codex automatise simplement la même fonction Git sous-jacente.