Worktrees Claude Code : des sessions en parallèle sans conflits de modifications

Les worktrees Claude Code, expliqués

Git gère les worktrees depuis des années : git worktree add extrait une branche dans un second répertoire, adossé aux mêmes données .git. Claude Code s’appuie là-dessus. Avec --worktree (ou -w), il crée le worktree pour vous, démarre la session à l’intérieur, bloque les modifications qui atterriraient dans votre checkout principal et propose de faire le ménage quand vous quittez.

Les worktrees isolent les fichiers, rien d’autre. Pour répartir une tâche entre plusieurs exécutants dans une seule conversation, utilisez des subagents ; pour comparer les options, voir plusieurs agents Claude Code.

• Emplacement par défaut : .claude/worktrees/<name>/ à la racine du dépôt.
• Nom de branche par défaut : worktree-<name>. Sans nom, Claude Code en choisit un, comme bright-running-fox.
• Partagé avec votre checkout : le répertoire .git (commits et branches sont donc visibles partout), les plugins de portée projet et les autorisations « ne plus demander ».
• Non partagé : tout ce qui est dans le .gitignore, comme .env, node_modules et les fichiers de build. Un worktree est un checkout neuf.

Le workflow des worktrees, étape par étape

1. Ignorez le dossier des worktrees

   Ajoutez .claude/worktrees/ au .gitignore, pour que les fichiers des worktrees n’apparaissent pas comme non suivis dans votre checkout principal. Si vous n’avez jamais lancé Claude dans ce dépôt, lancez d’abord claude une fois pour accepter la demande de confiance de l’espace de travail ; sinon, les lancements interactifs avec --worktree s’arrêtent aussitôt.

2. Une session par tâche

   Lancez claude --worktree <name> dans un terminal par tâche. Relancer la commande avec un nom existant rouvre ce worktree au lieu d’en créer un nouveau. Vous pouvez aussi demander à Claude en cours de session de « travailler dans un worktree » : il s’y installe lui-même avec l’outil EnterWorktree.

   # Deux sessions isolées, chacune dans son propre terminal
   claude --worktree feature-auth
   claude --worktree fix-flaky-test
   
   # Créer un worktree à partir de la pull request 1234 (mettez le # entre guillemets)
   claude --worktree "#1234"
   
   # Garder les worktrees hors de git status
   echo ".claude/worktrees/" >> .gitignore

3. Emportez les fichiers non suivis

   Listez les fichiers ignorés dont le projet a besoin, comme .env et .env.local, dans un fichier .worktreeinclude à la racine du dépôt, avec la syntaxe de .gitignore. Claude Code copie les fichiers correspondants dans chaque worktree qu’il crée, y compris ceux des subagents et de l’application desktop. Installez ensuite les dépendances dans le worktree, ou configurez-le dans les réglages : cet exemple part de votre travail en cours, réutilise un seul node_modules et n’extrait que le package web.

   {
     "worktree": {
       "baseRef": "head",
       "symlinkDirectories": ["node_modules"],
       "sparsePaths": [".claude", "packages/web"]
     }
   }

4. Laissez les sessions travailler

   Tant qu’une session est isolée, Claude Code refuse les modifications de fichiers qui visent le checkout principal, les commandes dont le répertoire de travail est le checkout principal et les commandes git redirigées vers lui (git -C, --git-dir, GIT_DIR). Il ne suit pas ce qu’écrit une simple commande shell comme cp : les permissions et le sandboxing restent donc importants.

5. Relisez et fusionnez comme n’importe quelle branche

   Chaque worktree est une branche normale. Committez et poussez depuis l’intérieur, ouvrez une pull request et relisez-la comme celle d’un coéquipier. Comme tous les worktrees partagent .git, la branche est visible tout de suite depuis votre checkout principal.

6. Quittez et faites le ménage

   Quand vous quittez, Claude Code vérifie le worktree. Un worktree propre issu d’une session sans nom est supprimé automatiquement avec sa branche ; une session nommée demande d’abord. S’il y a des modifications, des fichiers non suivis ou de nouveaux commits, il demande s’il faut garder ou supprimer le worktree, et affiche une commande claude --worktree <name> --resume pour y revenir plus tard.

Source : documentation de Claude Code, Run parallel sessions with worktrees

Les réglages des worktrees dans Claude Code

Tous se placent sous worktree dans un fichier de réglages (~/.claude/settings.json, .claude/settings.json ou .claude/settings.local.json).

Worktree Claude Code, branche ou git worktree

Le faire à la main avec git worktree

Passez par git directement quand vous voulez une branche existante précise ou un dossier hors du dépôt ; worktree.baseRef ne peut pas désigner une branche. Claude Code partage quand même les plugins et les autorisations avec ces worktrees.

1. Créez le worktree, lancez Claude, supprimez-le une fois fini

   Remplacez feature-a par un nouveau nom de branche, ou retirez -b pour extraire une branche qui existe déjà.

   git worktree add ../app-feature-a -b feature-a
   cd ../app-feature-a && claude
   git worktree list
   git worktree remove ../app-feature-a

Subagents et sessions en arrière-plan dans des worktrees

• Demandez à Claude d’« utiliser des worktrees pour tes agents », ou ajoutez isolation: worktree au frontmatter d’un subagent personnalisé dans .claude/agents/ : chaque subagent travaille alors dans son propre worktree temporaire.
• Le worktree d’un subagent sans modifications est supprimé quand le subagent termine. Celui qui contient des modifications reste jusqu’à ce qu’un nettoyage périodique puisse le supprimer sans perte, après cleanupPeriodDays.
• Les sessions en arrière-plan (claude --bg) ne modifient par défaut que l’intérieur d’un worktree ; lancez-en une avec claude --bg --worktree ou réglez worktree.bgIsolation sur "none".
• Dans l’application desktop, activez Worktree sous la zone de saisie avant de démarrer une session.

Nettoyage des worktrees et problèmes courants

• Les lancements claude -p --worktree n’ont pas de question à la sortie : ils laissent donc leurs worktrees derrière eux. Supprimez-les avec git worktree remove, après git worktree unlock si git indique qu’ils sont verrouillés.
• Can only use --worktree in a git repository : lancez git init et faites un premier commit, ou configurez un hook WorktreeCreate pour SVN, Perforce ou Mercurial.
• Les fichiers Git LFS apparaissent comme des fichiers pointeurs quand LFS a été installé avec --local : lancez git lfs pull dans le worktree.
• Claude Code ne crée pas de worktree quand .claude ou .claude/worktrees est un lien symbolique.
• Dans les hooks, ${CLAUDE_PROJECT_DIR} pointe toujours vers le checkout principal ; lisez le champ cwd de l’entrée du hook pour obtenir le chemin du worktree.
• Un worktree de base "fresh" sans commit propre, ou dont la PR a été fusionnée, revient à la branche par défaut quand vous le rouvrez par son nom.

Les worktrees séparent les sessions. Crewmark les fait travailler.

Les worktrees règlent le problème des collisions, mais chaque session reste inactive tant que vous n’écrivez rien. Crewmark transforme une session Claude Code, Codex, DeepSeek Harness ou OpenCode en employé IA avec un rôle, un objectif et des horaires de travail, et la réveille à intervalle régulier (heartbeat) pour qu’elle prenne la prochaine issue d’un tableau.

1. Un employé par worktree

   Donnez à chaque employé son propre worktree et son rôle, par exemple un développeur et un relecteur dans le même dépôt, comme dans plusieurs agents Claude Code.

2. Laissez la pulsation lancer le travail

   Pendant ses horaires de travail, chaque employé se réveille toutes les 15, 30 ou 60 minutes dans la même conversation ; voir comment rendre Claude Code proactif.

3. Assignez des issues et relisez les branches

   Mettez le travail sur le tableau ; chaque employé prend une issue, committe sur sa propre branche et vous écrit quand il a besoin d’une décision. Lisez ce qu’est un employé IA.

FAQ worktrees Claude Code