Codex Worktrees : faire travailler plusieurs agents en parallèle sans conflits

Les worktrees Git dans Codex permettent à plusieurs agents de travailler simultanément sur le même repo, chacun dans sa propre copie isolée du code. L’agent A refactorise le module d’auth pendant que l’agent B construit un nouvel endpoint API, et aucun ne touche les fichiers de l’autre. Zéro conflit de merge pendant le processus.

Disponibilité: App Codex desktop (macOS + Windows)
Prérequis: Projet dans un repo Git
Mécanisme: Git worktrees natifs (copies isolées partageant le même .git)
Handoff: Transfert de thread entre Local et Worktree via l’app
Automations: Exécution automatique dans des worktrees dédiés en arrière-plan
Limites: Une branche ne peut être checkoutée que dans un seul worktree à la fois

Qu’est-ce qu’un worktree Git ?

Avant de plonger dans l’implémentation Codex, rappelons le concept. Un worktree Git est une copie de travail supplémentaire de votre dépôt. Chaque worktree possède sa propre copie de tous les fichiers du repo, mais ils partagent tous les mêmes métadonnées Git (le dossier .git, les commits, les branches, etc.).

Concrètement, cela signifie que vous pouvez avoir plusieurs branches checkoutées et actives en même temps, dans des répertoires séparés. C’est exactement ce dont un outil de coding multi-agent a besoin : chaque agent travaille dans son propre répertoire, sur sa propre branche, sans jamais toucher aux fichiers des autres agents ou à votre checkout principal.

Dans l’app Codex, les worktrees sont intégrés nativement. Quand vous créez un thread en mode Worktree, Codex crée automatiquement un worktree Git basé sur la branche que vous choisissez. L’agent travaille dans cette copie isolée. Vous pouvez ensuite reviewer les changements, les transférer vers votre checkout local (handoff), ou ouvrir une PR directement depuis l’app.

Local vs Worktree : quand utiliser quoi

Quand vous créez un nouveau thread dans l’app Codex, vous choisissez entre deux modes :

Mode Local

L’agent travaille directement dans votre checkout principal, sur les fichiers que vous avez devant vous dans votre IDE. C’est le mode le plus simple et le plus direct.

Utilisez Local quand vous faites du pair-programming en temps réel avec Codex, quand vous voulez voir immédiatement les changements dans votre IDE, ou quand la tâche est simple et ne risque pas d’interférer avec votre travail en cours. Le mode Local est aussi le seul disponible pour les projets non versionnés (pas de Git).

Le risque : si l’agent modifie un fichier que vous êtes en train d’éditer, les deux modifications peuvent entrer en conflit. C’est pourquoi le mode Local est considéré comme le « premier plan » de votre workflow.

Mode Worktree

L’agent travaille dans une copie isolée de votre repo, sur sa propre branche. Vos fichiers locaux ne sont pas touchés.

Utilisez Worktree quand vous voulez explorer une idée sans risquer votre travail en cours, quand vous lancez plusieurs agents en parallèle sur le même repo, quand vous déléguez une tâche de fond (refactoring, migration, génération de tests) pendant que vous codez sur autre chose, ou quand vous voulez comparer plusieurs approches avant de choisir la meilleure.

Le mode Worktree est aussi utilisé automatiquement par les automations : chaque automation s’exécute dans son propre worktree dédié pour ne pas interférer avec votre travail ni avec d’autres automations.

Mental model : foreground vs background Pensez au mode Local comme le premier plan (vous codez activement) et au mode Worktree comme l’arrière-plan (des agents travaillent pendant que vous faites autre chose). Le Handoff vous permet de basculer un thread entre les deux.

Workflow pratique avec les worktrees

Créer un thread sur worktree

Dans l’app Codex, créez un nouveau thread et sélectionnez Worktree sous le champ de saisie. Vous pouvez optionnellement choisir un environnement local pour exécuter des scripts de setup dans le worktree (installation de dépendances, etc.).

Sous le champ de saisie, choisissez la branche Git de base pour le worktree. Les options sont : votre branche main/master, une branche de feature existante, ou votre branche actuelle avec les modifications locales non committées. Soumettez votre tâche. Codex crée le worktree et commence à travailler.

Par défaut, Codex travaille en « detached HEAD » dans le worktree. Quand vous êtes prêt, vous pouvez soit continuer à travailler directement sur le worktree, soit transférer le thread vers votre checkout local via le Handoff.

Reviewer les changements

L’app Codex intègre un panneau de diff qui affiche les changements Git effectués par l’agent dans le worktree. Depuis ce panneau, vous pouvez :

Voir le diff complet des modifications. Ajouter des commentaires inline pour que Codex les traite. Stager ou reverter des chunks spécifiques ou des fichiers entiers. Committer, pusher, et créer des PRs directement depuis l’app.

Chaque thread dispose aussi d’un terminal intégré, accessible avec Cmd+J (macOS) ou le bouton terminal en haut à droite. Ce terminal est scopé au worktree du thread, vous pouvez donc exécuter des tests, lancer un serveur de dev, ou faire des opérations Git sans quitter l’app.

Le mécanisme de Handoff

Le Handoff est le transfert d’un thread entre Local et Worktree. C’est la fonctionnalité qui rend le workflow fluide : vous déléguez du travail en arrière-plan (Worktree), puis vous le ramenez au premier plan (Local) quand vous êtes prêt à l’inspecter, le tester, ou le valider dans votre environnement habituel.

Sous le capot, le Handoff gère toutes les opérations Git nécessaires pour déplacer le travail entre deux checkouts en toute sécurité. C’est important parce que Git ne permet de checkouter une branche que dans un seul endroit à la fois. Si une branche est checkoutée dans un worktree, vous ne pouvez pas la checkouter dans votre local, et inversement. Codex gère cette contrainte automatiquement.

Deux scénarios d’utilisation du Handoff :

Worktree → Local : vous voulez ramener le travail de l’agent dans votre checkout principal pour le tester dans votre IDE, exécuter votre serveur de dev, ou valider les changements dans votre environnement quotidien. Cliquez sur « Hand off » dans l’en-tête du thread et sélectionnez Local.

Local → Worktree : vous voulez isoler un travail en cours pour qu’il ne bloque pas votre checkout principal. Utile quand vous voulez lancer une exploration longue sans monopoliser votre branche locale.

Chaque thread conserve son worktree associé dans le temps. Si vous transférez un thread vers Local puis le renvoyez vers Worktree, il retrouve le même worktree.

Travailler en parallèle : la mentalité d’abondance

OpenAI recommande une « mentalité d’abondance » avec les worktrees : au lieu de chercher la solution parfaite du premier coup, lancez plusieurs agents sur le même problème avec des approches différentes, puis comparez les résultats et gardez le meilleur.

En pratique, cela ressemble à ceci : vous avez un composant React à refactoriser. Vous créez trois threads en mode Worktree, chacun basé sur la même branche :

Thread 1 : « Refactorise le composant UserProfile en utilisant React Query pour la gestion d’état. »

Thread 2 : « Refactorise le composant UserProfile en utilisant Zustand avec des slices séparés. »

Thread 3 : « Refactorise le composant UserProfile en composants headless avec separation of concerns. »

Les trois agents travaillent en parallèle, chacun dans son worktree isolé. Quand ils terminent, vous reviewez les trois approches via les diffs dans l’app, choisissez la meilleure, et faites un Handoff vers Local ou ouvrez une PR.

Cette approche est aussi utile pour les migrations de dépendances, les changements d’architecture, ou toute tâche où plusieurs chemins sont viables et où le meilleur choix n’est pas évident avant d’avoir vu le code résultant.

Un développeur a testé cette approche sur un projet Next.js de taille moyenne avec trois agents en parallèle travaillant sur des features séparées. Résultat : zéro conflit de merge pendant le processus. Vous checkoutez la branche de chaque agent quand vous êtes prêt à reviewer, ou vous le laissez continuer.

Le pattern le plus productif est de consacrer les premières minutes de votre journée à lancer des worktrees sur les tâches que vous voulez déléguer (refactoring, génération de tests, documentation, migration), puis de travailler en Local sur les tâches qui nécessitent votre attention directe. En fin de journée, vous reviewez les résultats des worktrees et mergez ce qui convient.

Worktrees et automations

Les automations Codex utilisent des worktrees dédiés en arrière-plan pour les repos Git. Chaque automation crée son propre worktree, ce qui garantit que les modifications d’une automation ne touchent ni votre checkout local, ni les worktrees d’autres automations ou threads.

Pour les projets non versionnés, les automations s’exécutent directement dans le répertoire du projet (pas de worktree possible sans Git).

Accumulation de worktrees Les automations fréquentes créent des worktrees au fil du temps. Chaque worktree est une copie quasi-complète de votre repo sur disque. Sur un projet volumineux avec des automations toutes les heures, l’espace disque peut croître rapidement. Nettoyez régulièrement les worktrees obsolètes via le terminal (git worktree prune) ou depuis l’interface de gestion de l’app.

Worktrees et sous-agents

Codex supporte les workflows de sous-agents via spawn_agent et wait_agent. Les sous-agents peuvent eux aussi travailler dans des worktrees isolés, ce qui permet des architectures multi-agents complexes :

Un agent « chef de projet » reçoit la tâche globale et la découpe en sous-tâches. Il spawn des sous-agents, chacun dans son propre worktree, pour travailler en parallèle. Les sous-agents terminent et remontent leurs résultats. L’agent principal consolide, résout les éventuels conflits, et produit le livrable final.

La capacité spawn_agents_on_csv permet de fan-out du travail depuis un fichier CSV, avec un suivi de progression et des estimations de temps. Les sous-agents bénéficient de nicknames configurables et d’une UI claire dans l’app pour suivre l’avancement.

Opérations Git depuis l’app

L’app Codex intègre les opérations Git essentielles pour que vous n’ayez pas à quitter l’interface :

Diff pane : visualisez les changements Git de votre thread (local ou worktree). Commentez inline, stagez ou revertez des chunks ou fichiers entiers.

Commit et push : committez vos changements, pushez vers le remote, et ouvrez des PRs GitHub directement depuis l’app.

Terminal intégré : pour les opérations Git avancées (rebase, cherry-pick, résolution de conflits), utilisez le terminal scopé au worktree de votre thread. Codex peut lire la sortie du terminal, ce qui lui permet de vérifier l’état d’un serveur de dev ou de se référer à une sortie de build.

Ouvrir dans l’IDE : le bouton « Open » dans l’en-tête du thread ouvre le répertoire du worktree dans votre IDE favori pour une inspection plus poussée.

Bonnes pratiques

Splitter les monorepos en projets

Si vous travaillez dans un monorepo contenant plusieurs apps ou packages, créez des projets Codex séparés pour chaque partie distincte. Cela garantit que le sandbox de chaque agent ne contient que les fichiers pertinents pour sa tâche, ce qui améliore la qualité des résultats et réduit le contexte nécessaire.

Choisir la bonne branche de base

Pour les worktrees, choisissez la branche la plus récente et stable comme base. Utiliser main est généralement le bon choix. Si vous voulez que l’agent travaille sur une feature branch existante, assurez-vous que cette branche n’est pas déjà checkoutée ailleurs (contrainte Git).

Toujours reviewer avant de merger

Même si l’agent a produit du code qui passe les tests, reviewez toujours le diff avant de merger. Les worktrees facilitent cette review en gardant le travail de l’agent séparé de votre code. Utilisez le diff pane de l’app, ajoutez des commentaires inline pour les points à corriger, et laissez Codex itérer avant de valider.

Nettoyer les worktrees

Les worktrees terminés restent sur disque jusqu’à suppression explicite. Prenez l’habitude de nettoyer régulièrement, surtout si vous lancez beaucoup de threads en parallèle :

# Lister les worktrees existants
git worktree list

# Nettoyer les worktrees dont le répertoire a été supprimé
git worktree prune

# Supprimer un worktree spécifique
git worktree remove /chemin/vers/worktree

Documenter pour les agents

Les agents qui travaillent en worktree n’ont pas accès à vos fichiers locaux non committés ni à votre contexte IDE. Tout ce que l’agent doit savoir pour travailler efficacement doit être dans le fichier AGENTS.md, dans les skills, ou dans votre prompt. Si un agent en worktree produit des résultats médiocres, la cause est souvent un manque de contexte documenté.

Limites

Les worktrees nécessitent un repo Git. Les projets non versionnés ne peuvent pas les utiliser. Une branche ne peut être checkoutée que dans un seul worktree à la fois (contrainte Git, pas Codex). Cela signifie que si un agent a checouté feature/auth dans un worktree, vous ne pouvez pas la checkouter localement en même temps. Le Handoff gère cette contrainte automatiquement, mais il faut en être conscient pour les opérations Git manuelles.

L’espace disque peut devenir un problème sur les gros repos avec beaucoup de worktrees actifs. Chaque worktree contient une copie quasi-complète des fichiers du repo (bien que le dossier .git soit partagé). Surveillez votre espace disque si vous utilisez intensivement les worktrees parallèles.

Les worktrees ne sont actuellement disponibles que dans l’app Codex desktop, pas dans la CLI ou l’extension IDE. Pour du travail parallèle depuis la CLI, vous pouvez créer des worktrees Git manuellement et lancer des sessions Codex séparées dans chaque worktree.

Questions fréquentes sur les worktrees Codex

Faut-il savoir utiliser les worktrees Git pour utiliser cette fonctionnalité ?

Non. L’app Codex abstrait toute la complexité des worktrees Git. Vous cliquez sur « Worktree » quand vous créez un thread, vous choisissez une branche de base, et Codex gère tout le reste : création du worktree, checkout, commit, push, et nettoyage. Les commandes Git sous-jacentes sont cachées. Le seul concept à comprendre est la distinction Local (vos fichiers) vs Worktree (copie isolée).

Combien de worktrees peut-on avoir en parallèle ?

Il n’y a pas de limite technique imposée par Codex. La limite pratique est votre espace disque (chaque worktree est une copie quasi-complète des fichiers du repo), votre quota de crédits ChatGPT (chaque agent consomme des tokens), et votre capacité à reviewer les résultats. En pratique, 3 à 5 agents parallèles sont un bon équilibre entre productivité et maintenabilité.

Les worktrees fonctionnent-ils avec les sous-modules Git ?

Les worktrees Git standard supportent les sous-modules, et Codex hérite de ce comportement. Cependant, les sous-modules peuvent ajouter de la complexité lors du setup initial du worktree (initialisation et mise à jour des sous-modules). Documentez les commandes nécessaires dans votre AGENTS.md ou utilisez un script de setup via l’environnement local de l’app.

Que se passe-t-il si deux agents modifient le même fichier dans des worktrees différents ?

Tant que les agents sont dans des worktrees séparés, il n’y a aucun conflit pendant le travail. Chaque worktree a sa propre copie des fichiers. Le conflit potentiel ne survient qu’au moment du merge, quand vous essayez de fusionner les branches des deux worktrees. À ce stade, c’est un conflit Git classique que vous résolvez manuellement ou avec l’aide de Codex.

Les worktrees sont-ils disponibles dans la CLI ou l’extension IDE ?

L’interface de worktrees intégrée (création, Handoff, diff pane) est actuellement une fonctionnalité exclusive de l’app Codex desktop. Dans la CLI, vous pouvez créer des worktrees Git manuellement (git worktree add), puis lancer une session Codex dans ce répertoire avec codex --cd /chemin/vers/worktree. C’est moins intégré mais fonctionnel.