Git worktree avec Claude Code et Codex : guide pratique

Si vous faites tourner plus d’un agent de code sur un dépôt, il vous faut des git worktrees. Chaque agent travaille sur sa propre branche, dans son propre dossier, en même temps que les autres, sans leur marcher sur les pieds.

Qu’est-ce qu’un git worktree ?

Un clone classique a un seul arbre de travail : un dossier, une branche extraite. Un worktree est un dossier de travail supplémentaire rattaché au même dépôt, avec une autre branche extraite. Tous les worktrees partagent un même historique .git : un commit fait dans l’un est immédiatement visible dans les autres, mais leurs fichiers sont séparés.

Pour les agents, cela veut dire :

• Claude Code peut modifier les fichiers de ../atlas-auth sur feat/auth
• Codex peut modifier les fichiers de ../atlas-search sur feat/search
• Vous continuez à relire et à lancer l’app dans le dossier principal, sur main

Personne n’écrase les modifications de personne.

Un worktree par tâche

Depuis le dossier principal de votre dépôt :

# new branch + new folder next to the repo
git worktree add ../atlas-auth -b feat/auth
 
# another one, starting from a specific branch
git worktree add ../atlas-search -b feat/search origin/main
 
# see them all
git worktree list

Lancez ensuite un agent dans chaque dossier :

cd ../atlas-auth && claude
cd ../atlas-search && codex

Nommez les dossiers de worktree d’après leur tâche. Dans un mois, atlas-auth voudra encore dire quelque chose ; wt2, non.

Ou laissez Claude Code créer le worktree

Les versions récentes de Claude Code peuvent créer le worktree pour vous :

claude --worktree feature-auth   # or: claude -w feature-auth

Cette commande crée un worktree dans .claude/worktrees/feature-auth/, sur une nouvelle branche nommée worktree-feature-auth, et y démarre Claude. Relancez-la avec un autre nom dans un deuxième terminal pour une deuxième session isolée. Vous pouvez aussi demander à Claude de « travailler dans un worktree » en cours de session.

Quelques détails tirés de la documentation des worktrees Claude Code :

• Ajoutez .claude/worktrees/ à votre .gitignore pour que les fichiers des worktrees n’apparaissent pas comme non suivis dans votre copie principale.
• Le dépôt doit contenir au moins un commit.
• À la sortie, Claude supprime un worktree propre (en demandant d’abord pour un worktree nommé) et vous demande s’il faut garder un worktree qui contient encore des modifications.
• Un fichier .worktreeinclude liste les fichiers ignorés par git, comme .env, à copier dans chaque nouveau worktree.

Utilisez claude --worktree quand Claude Code est le seul agent sur la tâche. Utilisez git worktree add quand vous voulez choisir vous-même le dossier et le nom de branche, ou faire tourner Codex ou un autre agent dans le worktree.

Préparer chaque worktree avant de lancer l’agent

Un nouveau worktree ne contient que les fichiers suivis par git. Avant de le confier à un agent :

• Installez les dépendances. node_modules, les virtualenvs et les dossiers de build ne sont pas partagés. Lancez npm install (ou l’équivalent) dans chaque worktree. Les gestionnaires de paquets à stockage partagé, comme pnpm, rendent l’opération rapide.
• Copiez la configuration non suivie. Les fichiers .env et les réglages locaux sont en général ignorés par git : copiez ce dont l’app a besoin pour tourner. Avec claude --worktree, listez-les plutôt dans .worktreeinclude.
• Utilisez des ports différents. Deux serveurs de dev ne peuvent pas écouter tous les deux sur le port 3000. Démarrez le second sur un autre port, par exemple PORT=3001 npm run dev.
• Partagez les instructions via des fichiers suivis. CLAUDE.md et AGENTS.md sont versionnés dans git : chaque worktree les reçoit automatiquement.

Relire, fusionner et nettoyer

Quand un agent a terminé :

# in the worktree: check the work
git diff main...feat/auth
npm test
 
# in the main folder: merge
git merge feat/auth
 
# remove the worktree folder and its registration
git worktree remove ../atlas-auth
git branch -d feat/auth

Si vous avez supprimé un dossier de worktree à la main, lancez git worktree prune pour effacer l’entrée obsolète.

Les pièges courants

• « Branch is already checked out ». Une branche ne peut être extraite que dans un seul worktree à la fois. Créez plutôt une nouvelle branche pour chaque worktree.
• Les worktrees oubliés. Les vieux worktrees maintiennent des branches en vie et prennent de la place sur le disque. Lancez git worktree list de temps en temps.
• Des modifications non commitées à la suppression. git worktree remove refuse si le worktree contient des modifications. Commitez ou faites un stash d’abord, ou utilisez --force si vous voulez vraiment les abandonner.
• Des agents qui modifient le dossier principal. Démarrez chaque agent depuis son dossier de worktree, pas depuis la racine du dépôt.

Les worktrees dans Vibe Console

Vibe Console garde les worktrees visibles pendant que les agents y travaillent :

• L’onglet Worktrees du contrôle de source (⌘⇧G) liste chaque worktree avec sa branche, en signalant le worktree principal et les extractions détachées.
• Glissez un worktree sur un terminal pour coller son chemin, puis lancez-y un agent avec ⌘K.
• Supprimer le worktree fait le ménage quand vous avez terminé, et demande Forcer le retrait s’il reste des modifications locales. Le worktree principal est protégé.
• La grille affiche jusqu’à neuf terminaux : l’agent de chaque worktree peut avoir son propre panneau. Voir lancer des agents en parallèle.

Créez les worktrees avec git worktree add ou claude --worktree comme ci-dessus ; ils apparaissent tous les deux immédiatement dans la liste.

FAQ

Les worktrees prennent-ils beaucoup de place sur le disque ?

Seulement pour les fichiers extraits et ce que vous y installez. L’historique git est partagé.

Worktrees ou clones séparés ?

Les worktrees. Ils partagent un seul historique : branches et commits sont disponibles partout instantanément, et le nettoyage tient en une commande.

Deux agents peuvent-ils partager un worktree ?

Seulement si un seul d’entre eux, au plus, modifie des fichiers. Un agent relecteur qui ne fait que lire peut partager un worktree avec l’agent qui écrit le code.

Essayez-le gratuitement pendant 14 jours : téléchargez Vibe Console.