> ## Content Index > Fetch the complete content index at: https://www.sfeir.dev/llms.txt > Use this file to discover other available public pages before exploring further. # Git Worktree : exécuter plusieurs agents IA en parallèle sur un même repository - URL: https://www.sfeir.dev/ia/git-worktree-executer-plusieurs-agents-ia-en-parallele-sur-un-meme-repository/ - Published: 2026-02-27T10:30:12.000Z - Updated: 2026-02-27T10:30:12.000Z - Description: Git worktree : lancez plusieurs agents IA en parallèle sur un même repository, sans conflits Git. Tuto pas à pas avec Claude Code. - Author: Thomas GRUSON - Tags: IA, DevOps, git, Agentic, Productivité ## Introduction Vous lancez [*Claude Code*](https://www.sfeir.dev/ia/guides-claude-code-france-2025/) 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](https://incident.io/blog/shipping-faster-with-claude-code-and-git-worktrees?ref=sfeir.dev) : 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. 💡 Cet article utilise **Claude Code* pour les démos, mais ****le pattern** fonctionne avec ****n'importe quel agent IA** en terminal : **Codex CLI*, **Gemini CLI*, etc. 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 : ```bash # 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 ``` ⚠️ Contrainte : une branche ne peut être checkoutée que dans ****un seul worktree** à la fois. Si vous tentez de créer un second worktree sur la même branche, Git refusera. 💡 Ces commandes créent les worktrees à côté du repo principal. On verra plus loin ****comment les organiser proprement**. --- ## 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 : | Approche | Feature labels | Fix pagination | Refacto Pydantic | **Total** | | -------------------- | -------------- | -------------- | ---------------- | ---------- | | Séquentielle | 30 min | 15 min | 25 min | **70 min** | | Parallèle (3 agents) | 30 min | 15 min | 25 min | **30 min** | 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 ```bash # 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`. ![](https://storage.ghost.io/c/0b/31/0b31478e-a66a-46f1-8c34-d44388e21192/content/images/2026/02/git-worktree-multi-agent-ia_worktrees-1.png) 💡 ****Alternative : le pattern bare repo.** Pour ceux qui veulent une symétrie parfaite entre tous les worktrees (y compris `main`), le [pattern bare repo](https://morgan.cugerone.com/blog/how-to-use-git-worktree-and-in-a-clean-way/?ref=sfeir.dev) est une option. Le setup est plus complexe (`git clone --bare`, fichier pointeur `.git`, config du fetch), mais chaque worktree — main inclus — est traité de manière identique. Pour la majorité des cas, le dossier `worktrees/` \+ `.gitignore` fait le job. --- ## Mise en pratique : 3 agents, 3 worktrees, 1 repo On passe à la pratique avec un scénario concret. [**TaskFlow**](https://github.com/Thomgrus/taskflow?ref=sfeir.dev) : 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` : ```bash # 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 : ```bash cw feature-labels feature/labels # Terminal 1 cw fix-pagination fix/pagination # Terminal 2 cw refacto-pydantic-v2 refacto/pydantic-v2 # Terminal 3 ``` ⚠️ Chaque worktree a son propre système de fichiers mais ****pas d'environnement pré-installé**. Si votre projet utilise un `.venv` ou `node_modules`, pensez à lancer l'installation des dépendances dans chaque worktree (ou demandez-le à l'agent dans votre prompt). 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. 0:00 /0:11 1× ### É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. ```bash # 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](https://code.claude.com/docs/en/skills?ref=sfeir.dev) `/review-pr` pour automatiser avec un 4e agent. ### Étape 3 — Nettoyer ```bash 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](https://github.com/kbwo/ccmanager?ref=sfeir.dev), 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](https://www.anthropic.com/news/claude-opus-4-6?ref=sfeir.dev) 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](https://git-scm.com/docs/git-worktree?ref=sfeir.dev) - [Claude Code — Common Workflows (worktrees)](https://code.claude.com/docs/en/common-workflows?ref=sfeir.dev) - [incident.io — Shipping faster with Claude Code and Git Worktrees](https://incident.io/blog/shipping-faster-with-claude-code-and-git-worktrees?ref=sfeir.dev) - [Codex App — Worktrees](https://developers.openai.com/codex/app/worktrees/?ref=sfeir.dev) - [Pattern bare repo — How to use git worktree cleanly](https://morgan.cugerone.com/blog/how-to-use-git-worktree-and-in-a-clean-way/?ref=sfeir.dev) - [Git Worktrees — Nick Nisi](https://nicknisi.com/posts/git-worktrees/?ref=sfeir.dev) - [CCManager — Multi-session Claude Code](https://github.com/kbwo/ccmanager?ref=sfeir.dev) - [Claude Code — Skills](https://code.claude.com/docs/en/skills?ref=sfeir.dev)