Nethür
Se connecter
macOS bientôt disponible

Blog · 5 novembre 2026

Comprendre les worktrees de Claude Code

Un guide en langage clair sur les worktrees git dans Claude Code : ce qu’ils isolent, où ils se trouvent et comment les créer, les relire et les supprimer sans perdre de travail.

Schéma d’une branche main qui se divise en trois worktrees Nethür, un par tâche

Un worktree Claude Code est un worktree git ordinaire dans lequel vous lancez Claude Code. Git extrait une seconde copie du dépôt sur une autre branche, Claude Code utilise ce répertoire comme arbre de travail, et votre checkout principal reste intact. L’emplacement est celui que vous passez à `git worktree add`, ou le répertoire géré de l’outil qui le crée pour vous.

« 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/main

Gardez 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
claude

Utilisez 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.sharedDirectories dans nethur.yaml pour les définitions au niveau du dépôt.
  • Copier les petits fichiers propres au worktree. .worktreeinclude liste les fichiers et répertoires gitignorés à copier, comme .env ou 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.json

Les 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-login

Git 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 .env qui 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.

Passez le guide à la pratique.

Téléchargez Nethür et lancez votre premier agent en parallèle en quelques minutes, ou créez un espace de travail d’équipe sur une machine qui vous appartient déjà.