Worktrees git : faire travailler plusieurs agents de code en parallèle

Le problème : un seul dossier pour plusieurs agents

Un agent de code travaille dans un dossier : il lit les fichiers, les modifie, lance les tests et crée des commits. Tant qu’il est seul, tout va bien. Dès que vous lancez un second agent sur un autre besoin dans le même dossier, leurs changements se mélangent : l’un réécrit un fichier que l’autre est en train de tester, l’un change de branche sous les pieds de l’autre, et les tests rouges de l’un bloquent la livraison de l’autre.

La réponse habituelle consiste à cloner le dépôt une seconde fois. Cela fonctionne, mais chaque clone télécharge son propre historique, garde ses propres réglages et finit par diverger sans que personne ne s’en aperçoive. Git propose mieux depuis longtemps : le worktree.

Qu’est-ce qu’un worktree git ?

Un worktree est un dossier de travail supplémentaire rattaché au même dépôt. La commande git worktree add crée ce dossier et y extrait une branche. Tous les worktrees partagent le même historique et les mêmes objets git : un commit fait dans l’un est visible dans les autres, sans rien télécharger.

Chaque worktree a en revanche ses propres fichiers, sa propre branche extraite et son propre état : ce qui change dans l’un ne touche pas les autres. Git refuse d’ailleurs d’extraire la même branche dans deux worktrees à la fois, ce qui évite qu’un agent écrase le travail d’un autre sans le savoir.

Pour un agent de code, c’est exactement la bonne frontière : un dossier à lui, une branche à lui, et le même dépôt que les autres au moment de livrer.

Un besoin, un worktree, une branche

La règle qui rend les worktrees utiles est simple : un besoin par worktree. Une correction de bug, une nouvelle page, une migration : chacune a son dossier, sa branche et son agent. Le checkout principal reste propre et ne reçoit jamais de commit ; il sert de référence, pas de bureau.

Avec Treelab, lab new fait tout d’un coup : il crée le worktree sous .worktrees/, sa branche, la fiche du premier lot et un onglet dans cmux où l’agent démarre. Il copie aussi les fichiers locaux que vous avez déclarés, comme un fichier d’environnement, et installe les dépendances du projet d’après son fichier de verrouillage.

Vous choisissez l’agent de chaque worktree : Claude Code dans l’un, Codex dans l’autre. Les deux reçoivent les mêmes skills, les mêmes hooks et les mêmes agents de revue, et lab launch transmet à l’agent l’objectif écrit dans la fiche, sans rien à recopier.

$lab new project-1 feature-1 --title 'Add a search box' --agent claudePROJECT=project-1LANE=feature-1BRANCH=feat/feature-1BASE=origin/mainAGENT=claudelab: Next batches: unknown — planning will set them.$lab launch project-1 feature-1PROJECT=project-1LANE=feature-1AGENT=claudeSYNC=up-to-datePROMPT_BYTES=566

Mener plusieurs besoins en même temps

Une fois chaque besoin dans son worktree, vous en ouvrez autant que nécessaire. Chaque agent avance dans son onglet, sur sa branche, sans voir les fichiers des autres. Vous passez d’un onglet à l’autre pour répondre à une question ou approuver un plan, puis vous laissez l’agent continuer.

Le risque n’est plus le mélange des fichiers : c’est de perdre le fil. lab status dit où en est chaque worktree, avec sa branche, son lot courant, sa session et sa demande de fusion. lab plan recalcule l’avancement de tous à partir des fiches, à chaque affichage, sans tableau à tenir à jour.

Quand deux worktrees touchent les mêmes fichiers, lab status le signale aussi : vous savez quel besoin livrer d’abord, avant que le conflit n’arrive.

Livrer un worktree, puis le retirer

Un worktree n’a pas vocation à durer. Quand le besoin est livré, il doit disparaître, sinon les dossiers s’accumulent et plus personne ne sait lequel est à jour. Mais le retirer trop tôt fait perdre du travail : c’est l’erreur classique d’une suppression lancée au mauvais endroit.

Treelab sépare les deux gestes. lab merge livre un lot intermédiaire après avoir vérifié le bilan, la cible et les contrôles de la demande de fusion. À la fin, vous essayez le résultat ; lab acceptance note votre accord, puis lab close livre et retire le worktree, seulement après votre confirmation explicite.

Entre-temps, les garde-fous refusent par défaut les gestes qui effacent du travail, comme rm -rf hors du worktree ou git reset --hard, et donnent à l’agent l’alternative sûre. La page sécurité détaille ce qu’ils couvrent, et ce qu’ils ne couvrent pas.

Les pièges à connaître

Les dépendances : chaque worktree est un dossier neuf, sans node_modules ni environnement virtuel. Il faut les installer à la création, ce que lab new fait d’après le fichier de verrouillage du projet ; --no-install l’en dispense quand vous préférez le faire vous-même.

Les fichiers non suivis : un fichier .env ou une clé locale n’est pas dans git, donc pas dans le nouveau worktree. Déclarez-les une fois, Treelab les copie à chaque ouverture.

Le contexte de l’agent : un agent qui démarre dans un worktree neuf ne sait rien du besoin. Sans document de départ, il devine. C’est pourquoi chaque worktree Treelab commence par un cadrage et une fiche de lot, décrits dans le guide sur la méthode par lots.

Le vocabulaire : la CLI est en anglais, et ses messages appellent lane un besoin et son worktree. C’est la même chose sous un autre nom ; le glossaire donne aussi les anciens mots français.

Par où commencer

Pour essayer les worktrees à la main, git worktree add ../mon-besoin -b mon-besoin suffit, puis git worktree remove une fois le travail fusionné. Vous verrez vite ce que la discipline exige : nommer, installer, copier, suivre et retirer chaque dossier au bon moment.

Pour les mener avec un agent cadré, une fiche par lot et des garde-fous, Treelab installe tout en une commande. La page fonctionnalités montre chaque commande, et l’offre détaille la licence.