Git worktree : faire tourner plusieurs agents IA en parallèle sans qu'ils se marchent dessus

Un worktree par tâche pour lancer Claude Code ou Codex sur trois chantiers à la fois : les commandes, les pièges, puis relire et merger.

Claude Code ou Codex sur trois tâches à la fois, sans qu'ils réécrivent les fichiers les uns des autres. Le mécanisme existe déjà dans git : un dossier de travail par tâche, un historique partagé.

Le problème : deux agents, un seul dossier

Un agent de code lit, écrit et lance des commandes dans ton dossier de travail. Lance-en un deuxième dans le même dossier et tout se mélange : l'un change de branche pendant que l'autre écrit, l'un lance les tests sur le code à moitié modifié par l'autre, et le diff final contient les deux tâches emmêlées.

Cloner le dépôt une deuxième fois marche, mais tu dupliques tout l'historique et les branches ne se voient pas entre clones. Git a mieux : les worktrees.

Git worktree en trente secondes

Un worktree est un dossier de travail supplémentaire rattaché au même dépôt. Tous partagent un seul .git : mêmes commits, mêmes branches, mêmes remotes. Chacun a sa propre branche, ses propres fichiers et son propre état.

mon-projet/          → main         (ton dossier habituel, tu n'y touches pas)
mon-projet-export/   → feat/export  (agent 1)
mon-projet-auth/     → feat/auth    (agent 2)

Un commit fait dans mon-projet-export est visible tout de suite depuis mon-projet, sans push ni pull.

Un worktree par tâche

Depuis ton dépôt, une commande crée le dossier et la branche d'un coup. Place les worktrees à côté du dépôt, pas dedans.

cd mon-projet
git worktree add ../mon-projet-export -b feat/export
git worktree add ../mon-projet-auth -b feat/auth
git worktree list

-b crée une nouvelle branche à partir de ta position actuelle. Sans -b, tu donnes une branche existante : git worktree add ../mon-projet-fix fix/login.

git worktree list affiche chaque dossier, son dernier commit et sa branche. C'est ton tableau de bord.

Lancer un agent dans chaque worktree

Un terminal par worktree, un agent par terminal. L'agent ne voit que son dossier : il ne peut ni écraser ni tester le travail d'un autre.

# terminal 1
cd ../mon-projet-export && claude

# terminal 2
cd ../mon-projet-auth && codex

Claude Code sait aussi créer le worktree lui-même : claude --worktree export ouvre une session dans un nouveau worktree nommé export.

Écris des tâches qui ne se chevauchent pas. Les worktrees isolent les fichiers pendant le travail, pas au moment du merge. Deux agents qui modifient le même fichier produiront un conflit à la fin. Découpe par zone du code.

Les pièges à connaître

• Les dépendances ne sont pas partagées. Un worktree ne contient que les fichiers suivis par git : pas de node_modules, pas de .venv. Relance pnpm install ou uv sync dans chaque worktree. Avec pnpm, le store global évite de tout retélécharger.
• Les .env non plus. Ignorés par git, donc absents. Copie-les : cp .env ../mon-projet-export/.
• Une branche, un seul worktree. Git refuse d'extraire une branche déjà utilisée ailleurs : fatal: 'feat/export' is already used by worktree. C'est une protection, pas un bug.
• Les ports et la base locale sont partagés. Deux serveurs de dev sur le port 3000 se battent : PORT=3001 pnpm dev. Deux agents qui migrent la même base se gênent.
• Ta machine aussi. Trois agents, trois serveurs, trois suites de tests : sur un portable, deux ou trois chantiers est un plafond raisonnable.

Relire, merger, nettoyer

Relis tout ce que l'agent a changé par rapport à main, pas seulement son dernier message. Les trois points comparent depuis le moment où la branche est partie.

# depuis ton dossier principal
git diff main...feat/export
git merge feat/export

# puis on range
git worktree remove ../mon-projet-export
git branch -d feat/export

git worktree remove refuse de supprimer un dossier qui contient des modifications non commitées (--force si tu es sûr). La branche reste : supprime-la à part. Si tu as effacé un dossier à la main, git worktree prune nettoie les références.

Quand ça devient une équipe

À la main, la méthode tient pour deux ou trois chantiers. Au-delà, tu passes ton temps à créer des dossiers, copier des .env, surveiller des terminaux et relire des diffs.

C'est ce que j'automatise avec Vision Island : un worktree par tâche, un plan validé avant le code, une double revue sécurité et qualité avant le merge, sur un Mac mini qui tourne 24/7 avec un LLM local ou hybride, pour que rien ne sorte sans ta permission.

Les deux skills de revue (sécurité et qualité) sont open source : GITHUB_REPO_URL.

La version complète du guide, avec la FAQ : vision-island.com/guides/git-worktree-agents-ia