Guide Codex Worktree : développer plusieurs tâches IA en parallèle sans polluer le dépôt

Dans le même dépôt, trois tâches tournent en même temps : fix/auth-expired-session, test/payment-webhook et docs/setup-node20. Le git status du main checkout mélange maintenant des changements sans rapport : la correction du bug de login, des fichiers de test fixture et une note README sur Node 20. Les trois types de changements vivent dans le même checkout. Vous ne savez plus quelle partie peut être commitée seule, ni laquelle risque d’affecter les autres.

Ce n’est pas un problème abstrait de parallélisation. C’est ce qui arrive quand un checkout Git est pollué. Le mode Worktree de Codex app sépare les tâches dans des dossiers et des branches distincts, afin que chaque ligne de travail ait un diff vérifiable, mergeable et réversible.

Local / Worktree / Cloud : comment choisir le bon mode

Codex app propose trois modes d’exécution. Local et Worktree s’exécutent tous deux sur votre machine. La documentation officielle le dit clairement : “Both Local and Worktree threads will run on your computer”. Cloud, lui, tourne dans un environnement distant.

Le mode Worktree convient aux tâches indépendantes en parallèle ou aux expérimentations. Chaque thread a son propre dossier et sa propre branche, donc le main checkout reste intact. Le mode Local est simple, mais lorsque plusieurs tâches s’y mélangent, séparer les commits devient difficile. Le mode Cloud sort complètement de votre machine et convient aux workflows CI/CD et aux builds distants.

La règle de choix : une tâche unique en Local, du travail parallèle ou exploratoire en Worktree, les tâches distantes en Cloud.

Le mode Worktree de Codex app en détail

Création d’un Worktree et Handoff

Dans Codex app, le flux de création d’un Worktree thread ressemble à ceci :

1. Créer un nouveau thread
2. Choisir le mode Worktree (le nom exact dans l’UI peut changer après le 18/06/2026)
3. Choisir une branche de départ, ou travailler par défaut en detached HEAD
4. Envoyer le premier prompt
5. Codex commence à travailler dans un dossier isolé

Par défaut, Codex travaille en detached HEAD. Cela permet de continuer dans le worktree et de créer une branche au moment où l’on veut conserver le résultat. Handoff sert à déplacer un thread et son code entre Local et Worktree.

Scénarios de Handoff :

De Worktree vers Local : une fois la tâche terminée, créez d’abord une branche dans le worktree si vous êtes encore en detached HEAD, puis utilisez Handoff pour revenir en Local, avant de merger ou de créer une PR.

De Local vers Worktree : vous voulez déplacer un travail inachevé vers un environnement isolé pour éviter de polluer le main checkout.

Handoff n’est pas un simple changement de dossier. Il emporte aussi le contexte du thread, l’historique des prompts et les modifications inachevées.

Les particularités des Codex-managed worktrees

Les Codex-managed worktrees ont plusieurs comportements spécifiques :

Emplacement par défaut : $CODEX_HOME/worktrees

Nombre conservé par défaut : 15 worktrees (d’après la documentation du 18/06/2026), les plus anciens pouvant être nettoyés automatiquement

Permanent worktree : un worktree créé manuellement n’est pas supprimé automatiquement

Limite de branche : Git interdit de checkout la même branche dans plusieurs worktrees à la fois ; la tentative échoue

Héritage des règles : AGENTS.override.md est automatiquement copié dans le worktree pour garder les règles du projet cohérentes

En pratique : le nombre de worktrees est limité, les anciens peuvent être nettoyés, une même branche ne peut pas être utilisée en parallèle, et les règles du projet sont héritées.

.worktreeinclude pour gérer les fichiers ignorés

Par défaut, un worktree hérite des Git tracked files. Les fichiers présents dans .gitignore ne sont pas déplacés automatiquement pendant Handoff. Les manques fréquents : .env, .env.local, caches de dépendances, fichiers de configuration locale.

La solution consiste à créer un fichier .worktreeinclude à la racine du projet et à y lister les fichiers ignorés à copier. Exemple :

.env
.env.local
node_modules/.cache

Ainsi, les fichiers ignorés listés ici peuvent aussi être copiés vers le worktree pendant Handoff.

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Setup scripts : rendre le projet exécutable dans un worktree

Un worktree se trouve dans un dossier différent. Il peut donc manquer des dépendances ou des fichiers jamais check in. Les setup scripts s’exécutent lors de la création d’un nouveau worktree ou du démarrage d’un nouveau thread, afin de rendre l’environnement utilisable.

Étapes de configuration :

1. Configurer les setup steps dans Local environments de Codex app
2. Créer un dossier .codex pour les fichiers de configuration
3. Écrire des scripts spécifiques à la plateforme

Exemple pour un projet Node.js :

# .codex/setup.sh
npm install
npm run build

Exemple pour un projet Python :

# .codex/setup.sh
pip install -r requirements.txt
python manage.py migrate

Les setup scripts s’exécutent à chaque création de worktree. Ils évitent d’installer les dépendances à la main. Attention : l’UI de configuration et le format des fichiers peuvent évoluer après le 18/06/2026 ; vérifiez la documentation actuelle.

Sans Codex app, Plain Git worktree isole aussi le travail

Si vous préférez le CLI ou le terminal, vous pouvez créer directement des dossiers isolés avec Git worktree, puis démarrer Codex dans chaque dossier. Vous n’avez pas besoin de la gestion Codex app, mais toute l’administration vous revient.

Commandes Git Worktree courantes :

# Créer un nouveau worktree et une branche, dans le style du cas d'usage officiel
git worktree add ../analysis-highway-eda -b analysis/highway-eda

# Créer un nouveau worktree à partir d'une branche existante
git worktree add ../task-b existing-branch

# Lister tous les worktrees
git worktree list

# Supprimer un worktree
git worktree remove ../task-a

# Nettoyer les métadonnées de worktree obsolètes
git worktree prune

Comparaison entre Codex-managed et Plain Git :

Plain Git worktree convient aux développeurs qui aiment le CLI, mais vous devez gérer vous-même l’installation des dépendances, la configuration de l’environnement et le nettoyage. Les Codex-managed worktrees automatisent une partie de ce travail.

Les automations en arrière-plan doivent-elles utiliser worktree ?

Dans un dépôt Git, une automation peut tourner dans le local project ou dans un dedicated background worktree. Le choix dépend du type de tâche et du niveau de risque.

Logique de décision :

Le mode Local convient aux tâches ponctuelles et aux tests temporaires. Il modifie directement le main checkout, donc le travail inachevé peut être pollué. Si vous êtes en train d’éditer un fichier, une background automation peut modifier le même fichier.

Le mode Worktree convient aux tâches répétées ou planifiées. Il sépare les automation changes de l’unfinished local work. L’automation tourne dans un dossier indépendant et n’affecte pas le main checkout.

Points de risque :

Les Automations utilisent les default sandbox settings, qui peuvent évoluer après le 18/06/2026

Avec full access, les background automations sont plus risquées ; elles devraient donc utiliser worktree

Ne lancez pas de tâches de fond répétées directement dans Local

Principe : Local suffit pour une tâche temporaire ponctuelle ; Worktree s’impose pour les tâches répétées et le full access en arrière-plan.

Quelles tâches peuvent être parallélisées, lesquelles doivent rester séquentielles

Les cas d’usage officiels recommandent de séparer les explorations dans des worktrees différents. En pratique, il faut tout de même juger les conflits de fichiers et les dépendances entre tâches.

Table de décision pour les tâches parallèles :

Principes de parallélisation :

Commencez avec deux petites tâches indépendantes, pas cinq ou six d’un coup.

Gardez 3 à 4 tâches au maximum pour limiter le coût de revue.

Donnez à chaque tâche un critère de validation clair.

Évitez la parallélisation excessive. Plus il y a de tâches parallèles, plus le coût de revue et le risque de merge conflict augmentent.

Modèle de fiche de tâche : écrire clairement ce que chaque worktree doit faire

Avant de démarrer un worktree, écrivez la tâche de façon claire pour faciliter la validation et le suivi.

Exemple de fiche de tâche :

Goal: "Corriger le bug session expired dans le module auth"
Context:
  - "La session expire après 30 minutes, mais le frontend n'affiche aucune alerte"
  - "Fichiers concernés : src/auth/session.js, src/components/AuthProvider.jsx"
Constraints:
  - "Ne pas modifier le schema de base de données"
  - "Ne pas ajouter de nouvelle dépendance"
Done when:
  - "Le frontend affiche une alerte quand la session expire"
  - "npm test passe"
  - "Le flux de login est testé manuellement"

Branch/Worktree: "fix/auth-expired-session"
Commande de vérification: "npm test && npm run lint"

Éléments à remplir :

Goal : décrire l’objectif en une phrase

Context : fournir le contexte, les fichiers, les modules et l’arrière-plan

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Constraints : fixer les limites, y compris ce qui ne doit pas changer

Done when : lister des critères de fin vérifiables

Branch/Worktree : choisir un nom clair, par exemple task-type/module-description

Commande de vérification : donner une commande réellement exécutable

Chaque worktree a ainsi une frontière claire. Pendant la revue, il suffit de comparer le résultat avec Done when.

File de merge : review, test, merge, une tâche à la fois

Quand les tâches parallèles sont terminées, ne versez pas tout dans main en une seule fois. Triez-les par risque, puis relisez, testez et mergez une par une.

Étapes de la file de merge :

1. Trier les worktrees par risque, en commençant par le plus faible
2. Pour le premier worktree :
   • Lancer la commande de vérification : tests, lint
   • Examiner le diff et confirmer le périmètre des changements
   • Créer une branche si vous êtes encore en detached HEAD
   • Relire le diff selon vos règles de PR review
3. Merger vers Local ou créer une PR :
   • Merge local : Handoff vers Local, puis merge
   • Merge via PR : créer une PR, attendre CI et review
4. Répéter ces étapes pour le worktree suivant
5. Une fois tout terminé, merger vers la branche main

Checklist de validation :

Les commandes de vérification passent : tests et lint

Contrôle du diff : le périmètre correspond à la tâche

Review guidelines : pas de fichiers sensibles, pas de secrets hard-coded

CI passée, si disponible

Flux de test manuel

Points de risque :

Ne promettez pas de fusion automatique des résultats de plusieurs worktrees

Si plusieurs tâches modifient le même fichier, résolvez les conflits à la main

Gardez une revue humaine et des tests

Le but d’une file de merge est de rendre chaque ligne de travail reviewable et réversible, pas de soumettre tous les changements d’un coup.

Checklist de dépannage

Erreur "branch already used by worktree"

Cause : la branche est déjà utilisée par un autre worktree

Solution :

Utilisez git worktree list pour voir quelles branches sont occupées

Choisissez une autre branche ou supprimez le worktree qui utilise cette branche

Le code ne tourne pas dans le worktree

Cause : des dépendances ou des fichiers de configuration manquent

Étapes de diagnostic :

Vérifiez si .env et .env.local existent ; ils n’ont peut-être pas été copiés

Vérifiez si les dépendances sont installées, comme node_modules ou venv

Vérifiez si les fichiers de configuration sont complets

Solution :

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Configurer .worktreeinclude pour copier les ignored files

Configurer les Setup scripts pour installer automatiquement les dépendances

L’espace disque des worktrees gonfle

Cause : des automations fréquentes créent beaucoup de worktrees

Solution :

Archivez les automation runs devenus inutiles

Lancez manuellement git worktree prune pour nettoyer les worktrees obsolètes

Vérifiez le réglage de conservation des worktrees dans Codex app, qui peut évoluer après le 18/06/2026

Un worktree créé par l’agent ne correspond pas au contexte UI/thread

Cause : lorsqu’un agent crée lui-même un worktree, il peut contourner l’App UI

Solution :

Utilisez git worktree list pour inspecter tous les worktrees

Vérifiez manuellement dans l’app le lien entre thread et worktree

Évitez de laisser l’agent créer automatiquement des worktrees ; passez plutôt par l’App UI

Le réflexe de dépannage consiste à inspecter d’abord l’état des worktrees avec git worktree list, puis à traiter l’erreur précise.

Coût : les tâches parallèles consomment plus vite le quota

Les tâches parallèles ont tendance à consommer plus de tours ou de quota. Chaque worktree est une session indépendante, et Codex comptabilise chaque session séparément.

Règles de coût :

Gardez le nombre de tâches parallèles autour de 3 à 4.

Commencez par deux petites tâches indépendantes pour réduire le coût de revue.

Donnez à chaque tâche un critère de validation clair afin d’éviter les itérations sans fin.

Pour les prix, quotas et plans précis, renvoyez-vous à un futur article sur Cost & Quota. Cette page ne répète pas de chiffres non vérifiés.

Prochaines étapes et lectures associées

Articles amont :

Choisir son entrée Codex : brève introduction aux modes Local / Worktree / Cloud

Règles de projet AGENTS.md : comment chaque worktree hérite des mêmes règles de projet