Git Worktree : exécuter plusieurs agents IA en parallèle sur un même repository

Introduction

Vous lancez Claude Code sur une feature. Pendant qu'il bosse, vous attendez. Et si vous pouviez lancer 3 agents en même temps ?

C'est exactement ce que fait l'équipe d'incident.io : plusieurs agents Claude Code en parallèle, chacun sur sa tâche. Résultat : un éditeur JavaScript livré en 10 minutes au lieu de 2 heures estimées, des features low-priority qui deviennent réalisables en un coup. Le secret : git worktree — une commande native de Git que peu de devs connaissent.

Au programme :

1. Git worktree, les bases
2. Pourquoi c'est le setup idéal pour le multi-agent ?
3. Organiser ses worktrees sans que ça devienne le bordel !
4. Mise en pratique step-by-step
5. Bonnes pratiques et pièges à éviter

Git Worktree en 2 minutes

Un worktree, c'est un checkout d'une branche dans un répertoire séparé. Contrairement à git clone, il n'y a pas de duplication du repo : tous les worktrees partagent le même .git — historique, remotes, stash, tout.

Concrètement : au lieu de switcher de branche dans un seul dossier, vous avez un dossier par branche. Chacun avec ses propres fichiers, son propre état.

3 commandes à retenir :

# Créer un worktree avec une nouvelle branche
git worktree add ../feature-labels -b feature/labels

# Lister les worktrees actifs
git worktree list

# Supprimer un worktree
git worktree remove ../feature-labels

Pourquoi c'est le setup idéal pour le multi-agent IA ?

Le problème : Deux agents IA dans le même répertoire = crash garanti. Git utilise un fichier index.lock pour verrouiller le staging area. Deux agents qui écrivent en même temps → pas de file d'attente, le second plante immédiatement : fatal: Unable to create '.git/index.lock': File exists.

La solution : un worktree par agent. Chaque worktree a son propre index, ses propres fichiers. Zéro interférence.

• Isolation complète : chaque agent travaille sur ses fichiers sans toucher aux autres
• Vraie parallélisation : feature + bugfix + refacto en simultané
• Pas de conflits Git : chaque worktree a sa propre branche, son propre working directory

Support natif des agents IA

Les agents IA modernes gèrent nativement les worktrees :

• Claude Code : fonctionne nativement dans un worktree, chaque session est isolée
• Codex CLI : utilise les worktrees nativement pour isoler ses automations en background
• Gemini CLI, Aider, etc. : tout agent CLI fonctionne nativement dans un worktree

Le gain, en image

Prenons un scénario concret — 3 tâches indépendantes sur une même API :

3 agents en parallèle = le temps total est celui de la tâche la plus longue. Ici : 30 min au lieu de 70.

Organiser ses worktrees sans que ça devienne le bordel !

L'approche naïve — git worktree add ../mon-worktree — crée des dossiers en vrac à côté du repo. Avec 3-4 worktrees, votre dossier projets devient illisible.

❌ Anti-pattern : les dossiers en vrac

~/projects/
├── taskflow/              # repo principal
├── taskflow-labels/       # worktree 1... c'est quoi ce dossier ?
├── taskflow-fix/          # worktree 2
├── taskflow-pydantic/     # worktree 3
├── autre-projet/          # ah non ça c'est un autre projet
└── autre-projet-hotfix/   # ... ou un worktree ?

Impossible de distinguer les worktrees des vrais projets au premier coup d'œil.

✅ Recommandé : un dossier `worktrees/` dans le repo

L'approche la plus simple : créer les worktrees dans un sous-dossier worktrees/ du repo, ajouté au .gitignore. Pas besoin de bare repo, pas de config spéciale — un clone classique suffit.

~/projects/taskflow/
├── .gitignore             # contient "worktrees/"
├── src/                   # code source (branche main)
├── tests/
└── worktrees/
    ├── feature-labels/    # worktree feature
    ├── fix-pagination/    # worktree bugfix
    └── refacto-pydantic-v2/ # worktree refacto

Tout est contenu dans le repo. Un ls worktrees/ suffit pour voir tous les contextes de travail actifs.

Setup

# Ajouter worktrees/ au .gitignore
echo "worktrees/" >> .gitignore

# Créer un worktree
git worktree add worktrees/feature-labels -b feature/labels

git status sur main : clean. Les worktrees sont invisibles pour Git grâce au .gitignore.

Mise en pratique : 3 agents, 3 worktrees, 1 repo

On passe à la pratique avec un scénario concret. TaskFlow : une API REST Python/FastAPI de gestion de tâches. 3 tâches indépendantes à livrer :

1. Feature : ajouter un système de labels/tags sur les tâches
2. Bugfix : corriger un bug de pagination off-by-one sur GET /tasks
3. Refacto : migrer la validation des inputs de Pydantic v1 vers v2

Étape 1 — Créer les worktrees et lancer les agents

Avec le repo cloné et worktrees/ dans le .gitignore (cf. section précédente), ajoutez cette fonction à votre .bash_profile / .zprofile :

# Créer un worktree et lancer claude dedans
cw() {
  local name="$1"
  local branch="${2:-feature/$1}"
  git worktree add "worktrees/$name" -b "$branch"
  cd "worktrees/$name" && claude
}

Un worktree + un agent en une commande. Ouvrez 3 terminaux :

cw feature-labels feature/labels       # Terminal 1
cw fix-pagination fix/pagination       # Terminal 2
cw refacto-pydantic-v2 refacto/pydantic-v2  # Terminal 3

Puis donnez le contexte à chaque agent :

Agent 1 : Ajoute un système de labels sur les tâches : nouveau modèle Label, relation many-to-many avec Task, routes CRUD /labels et /tasks/{id}/labels, et les tests associés.

Agent 2 : Corrige le bug de pagination sur GET /tasks : il y a un off-by-one, la première page retourne n-1 résultats. Ajoute un test de régression.

Agent 3 : Migre la validation des inputs de Pydantic v1 vers Pydantic v2 : remplace les validators par @field_validator, mets à jour les model_config, et vérifie que tous les tests passent.

Étape 2 — Code, PR et review

Évidemment, en pratique on ne merge pas en local comme un sauvage. Chaque agent peut créer sa PR directement.

# Depuis le worktree feature-labels
gh pr create --title "feat: système de labels/tags" --body "..."

Ou demandez-le à l'agent directement — Claude Code sait utiliser gh :

Crée une PR pour cette branche avec un résumé des changements.

Résultat : 3 PRs prêtes à review en parallèle. Vos collègues peuvent reviewer — ou créez un custom skill /review-pr pour automatiser avec un 4e agent.

Étape 3 — Nettoyer

git worktree remove worktrees/feature-labels
git worktree remove worktrees/fix-pagination
git worktree remove worktrees/refacto-pydantic-v2

🎉 3 tâches livrées en parallèle, PRs créées, worktrees nettoyés.

Bonnes pratiques et pièges à éviter

💡 Tips

• worktrees/ + .gitignore — le setup le plus simple, adoptez-le dès le départ
• La fonction cw dans votre shell — un worktree + un agent en une commande
• /rename vos sessions — "labels", "fix-pagination" est plus lisible que "session_2f8a3b"
• Tâches indépendantes = merge sans conflit — c'est la clé du workflow, découpez bien vos tâches
• Ajoutez la convention worktree dans votre CLAUDE.md — toute l'équipe adopte le réflexe sans avoir à l'expliquer à chaque session
• Pour les power users : CCManager, un gestionnaire CLI qui affiche le statut de vos sessions multi-agents en temps réel, sans jongler entre les terminaux

⚠️ Pièges

• Une branche = un seul worktree — si la branche est déjà checkoutée ailleurs, Git refusera
• Ne supprimez pas un worktree sans avoir mergé ou push — les commits locaux seraient perdus
• .venv et node_modules ne sont pas partagés — chaque worktree a les siens, prévoyez l'espace disque
• Ne parallélisez pas des micro-tâches — créer un worktree + une PR pour un changement de 2 minutes, c'est du overhead inutile. Réservez les worktrees aux tâches qui prennent au moins 5-10 minutes chacune
• Sous-agents en background ≠ 3 terminaux — un agent qui orchestre et lance des sous-agents en background, c'est séduisant sur le papier. En pratique, quand un sous-agent a besoin d'une permission, elle est auto-refusée silencieusement : l'action n'est jamais exécutée, mais le sous-agent peut continuer comme si de rien n'était. Pas de notification, pas d'erreur visible. Préférez un terminal par agent : vous gardez le contrôle et vous voyez ce qui se passe
• 3 agents = 3x les tokens — surveillez vos coûts, surtout avec des modèles comme Opus

Conclusion

Git worktree transforme le multi-agent IA d'un concept cool en workflow concret. Le vrai gain n'est pas juste la vitesse : c'est un workflow reproductible — worktrees/ + convention d'équipe — que n'importe qui peut adopter en 5 minutes.

Et ce n'est que le début. Avec les Agent Teams d'Anthropic et les agents multi-tâches de Codex, l'orchestration multi-agent va devenir la norme.

La prochaine fois que vous avez 3 tâches indépendantes à livrer, essayez 3 worktrees. Vous ne reviendrez pas en arrière.

Sources :

• Doc officielle git worktree
• Claude Code — Common Workflows (worktrees)
• incident.io — Shipping faster with Claude Code and Git Worktrees
• Codex App — Worktrees
• Pattern bare repo — How to use git worktree cleanly
• Git Worktrees — Nick Nisi
• CCManager — Multi-session Claude Code
• Claude Code — Skills