« Worktree Claude Code » sonne comme une fonctionnalité à activer. La plupart du temps, c’est plus simple : un worktree est un répertoire que git crée, et Claude Code est un processus qui modifie des fichiers dans le répertoire où vous le lancez. Mettez ces deux faits bout à bout et vous obtenez des sessions d’agents isolées.
La distinction compte, parce que le web mélange trois choses : les worktrees git, les fonctionnalités de worktree dans les applications de Claude Code, et les outils d’espace de travail qui créent des worktrees pour vous. Ils partagent un nom et un objectif, mais l’emplacement, le nettoyage et la relecture changent selon qui a créé le répertoire.
Ce qu’est vraiment un worktree git
Un clone normal possède un seul arbre de travail : les fichiers que vous voyez dans votre éditeur. Un worktree git permet au même dépôt d’avoir plusieurs arbres de travail à la fois, chacun sur une branche différente. La base d’objets et les remotes sont partagés ; les fichiers extraits et l’index ne le sont pas.
git worktree list
# /Users/you/app abc1234 [main]
# /Users/you/app-fix-login def5678 [fix/login]- Chaque worktree a sa propre branche, son HEAD, son index et ses fichiers sur le disque.
- Impossible d’extraire la même branche dans deux worktrees à la fois.
- Supprimer un worktree retire le répertoire et son checkout, pas l’historique de la branche.
- Chaque worktree reste le même dépôt : commits, fetch et push voient les mêmes objets.
C’est exactement l’isolement dont un agent a besoin. Claude Code peut lire, modifier, lancer des tests et commiter dans son worktree sans toucher au checkout que vous avez ouvert. Si l’agent casse quelque chose, vous supprimez le répertoire et gardez votre branche principale.
Pourquoi Claude Code gagne à travailler dans un worktree
Une session d’agent n’est pas un chat qui touche des fichiers par hasard. Elle lance des commandes, démarre des serveurs de dev, écrit des fichiers générés, met des changements en index et change parfois de branche. Deux sessions dans un même checkout partagent tout cet état. L’échec est rarement spectaculaire : un test passe sur le mauvais code, un formatter réécrit le travail de l’autre agent, ou un commit embarque des fichiers des deux tâches.
Un worktree transforme ces défaillances d’état partagé en répertoires séparés. Le prix, c’est que chaque nouveau worktree démarre propre : pas de node_modules, pas de .env, pas de base locale. Le reste de ce guide consiste surtout à payer ce prix volontairement.
Claude Code a-t-il un mode worktree ?
Le CLI Claude Code n’a pas besoin d’un mode spécial pour travailler dans un worktree. Sa frontière de session, c’est le répertoire de travail. Lancez claude dans ../app-fix-login et la session lit et écrit là ; lancez-en une autre dans ../app-fix-billing et elle a une autre branche et un autre ensemble de fichiers.
D’autres surfaces Claude Code gèrent les worktrees pour vous. L’application de bureau peut lancer des sessions parallèles dans des worktrees git isolés, et les équipes d’agents ou les sous-agents peuvent déléguer du travail au sein d’une session. Ce sont des couches de confort : elles créent un checkout, y placent l’agent et masquent le chemin. Si vous voulez un emplacement prévisible, créez le worktree vous-même et lancez Claude Code dedans.
Où placer un worktree Claude Code ?
L’emplacement dépend de qui crée le worktree. Pour une installation manuelle, passez un chemin à git worktree add. Deux conventions fonctionnent bien : un répertoire voisin du checkout principal, ou un dossier worktrees/ dédié en dehors du dépôt.
# sibling next to the main checkout
git worktree add ../app-fix-login -b fix/login origin/main
# or a dedicated root outside the repo
git worktree add ~/worktrees/app/fix-login -b fix/login origin/mainGardez les worktrees en dehors du checkout principal. Un worktree placé dans le dépôt apparaît dans chaque recherche, perturbe l’indexation de l’éditeur et peut être commité par accident. Si un outil crée des worktrees dans un dossier caché à l’intérieur du dépôt, vérifiez que ce dossier est bien gitignoré avant de vous appuyer dessus.
Nethür crée les worktrees dans son propre répertoire géré et suit le chemin pour vous. Si vous avez déjà des worktrees créés par Claude Code, GSD ou un simple git worktree add, Nethür peut les afficher comme worktrees externes au lieu de vous demander de les déplacer. Réglages → Général → Espace de travail contrôle quelles sources externes sont visibles et quels répertoires racines sont scannés.
Si vous préférez ne pas gérer les chemins à la main, une interface graphique de worktree git comme Nethür peut créer, suivre et nettoyer les worktrees à votre place, tout en laissant un checkout normal sur le disque.
Créer un worktree et lancer Claude Code
Partez d’une ref de base à jour pour que l’agent ne travaille pas sur le code de la semaine dernière.
git fetch origin
git worktree add ../app-fix-login -b fix/login origin/main
cd ../app-fix-login
claudeUtilisez un nom de branche unique par worktree. Si vous voulez un second agent sur la même tâche, créez un second worktree avec une branche différente, même si le prompt est identique. C’est la branche qui rend les deux résultats comparables et mergeables indépendamment.
Dans Nethür, la même étape est une boîte de dialogue : créez un worktree, nommez la tâche, choisissez la ref de départ et sélectionnez l’agent. Nethür lance git fetch et git worktree add en arrière-plan, affiche l’espace de travail pendant sa création et ouvre l’agent dans le nouveau checkout. La documentation des worktrees couvre le sélecteur de ref de départ, les espaces de dossier et les tickets liés.
Dépendances, fichiers d’env et ports
Un worktree neuf est un checkout propre, donc il lui manque tout ce que git ignore. Trois approches existent, et la plupart des équipes finissent par les combiner.
- Installer par worktree. Correct et simple, mais lent et gourmand en disque quand chaque agent veut ses propres
node_modules. - Partager les répertoires lourds et reconstructibles. Les chemins partagés de worktree de Nethür matérialisent les répertoires gitignorés depuis le checkout principal, avec
worktree.sharedDirectoriesdansnethur.yamlpour les définitions au niveau du dépôt. - Copier les petits fichiers propres au worktree.
.worktreeincludeliste les fichiers et répertoires gitignorés à copier, comme.envou les réglages locaux de l’éditeur, pour que chaque worktree ait sa propre copie.
# nethur.yaml at the repo root
worktree:
sharedDirectories:
- node_modules
- .cache
# .worktreeinclude at the repo root
.env
.env.local
.vscode/settings.jsonLes ports méritent leur propre règle. Si deux agents démarrent le même serveur de dev, le second échoue ou, pire, se connecte à la base du premier. Mettez le port et le nom de la base dans un fichier d’environnement par worktree, ou faites dériver ces valeurs du nom du worktree par le hook de préparation.
Relire le diff, puis supprimer le worktree
Relisez chaque worktree par rapport à la ref depuis laquelle il est parti, pas par rapport à ce qui se trouve sur main aujourd’hui. Le diff reste ainsi centré sur le travail de l’agent. Nethür affiche le diff par espace de travail, prend en charge les annotations en ligne et peut renvoyer des notes de relecture à l’agent avant que vous ne commitiez.
Une fois le travail mergé, supprimez le worktree et la branche. Ne supprimez pas le répertoire à la main : git conserve des métadonnées sous .git/worktrees, et un rm -rf manuel laisse une entrée fantôme.
git worktree remove ../app-fix-login
git branch -d fix/login
# if git refuses because the branch has unmerged commits
git worktree remove --force ../app-fix-loginGit peut conserver une branche locale contenant des commits non mergés même après la disparition du worktree. C’est un filet de sécurité, pas un bug. Nethür expose les branches conservées dans une étape de relecture, pour que vous décidiez lesquelles supprimer de force au lieu de les chercher plus tard.
Les erreurs courantes avec les worktrees
- Extraire la même branche dans deux worktrees. Git refuse ; choisissez une autre branche pour le second agent.
- Placer le worktree dans le dépôt. Recherches et éditeurs voient des fichiers en double, et le répertoire peut être commité.
- Partager un seul
.envqui pointe vers la base principale. Chaque agent devrait avoir sa propre base ou son propre schéma dès qu’il y a des migrations. - Oublier la ref de base. Un worktree créé depuis une branche locale obsolète produit un diff confus et un merge douloureux.
- Laisser des dizaines de worktrees ouverts après l’expérience. Nettoyez les branches pendant que vous vous souvenez encore laquelle a gagné.
Les worktrees en équipe
Sur un serveur d’équipe, les worktrees cessent d’être des répertoires privés. Ils deviennent un état de projet partagé : un coéquipier voit qu’un worktree existe, qui l’a créé, quel agent tourne et s’il est bloqué. Cette visibilité est ce qui rend la passation sûre.
Nethür conserve le même modèle de worktree que le serveur tourne sur votre ordinateur portable, la machine d’un coéquipier, un VPS ou une cible SSH. L’agent tourne là où vit le checkout, et le client ne fait qu’afficher la session. Pour la version équipe de cette configuration, lisez Claude Code pour les équipes.
Essayez sur une seule tâche
Créez un worktree pour une petite modification, lancez Claude Code dedans et gardez votre checkout principal ouvert à côté. Une fois que vous voyez les deux sessions cesser de s’interférer, le répertoire supplémentaire cesse de ressembler à une charge. Le guide des agents parallèles montre comment passer à plusieurs agents et comparer leurs résultats.



