Exécuter des sessions parallèles avec worktrees

​

Démarrer Claude dans un worktree

claude --worktree feature-auth

​

Configurer l’environnement du worktree

​

Demander à Claude de créer un worktree

​

Nettoyer les worktrees

• Le worktree est propre : pour une session sans nom, Claude supprime le worktree et sa branche automatiquement. Une session nommée vous demande d’abord pour que vous puissiez conserver le worktree pour plus tard
• Le worktree contient du travail : Claude vous demande de conserver ou de supprimer le worktree. Conserver préserve le répertoire et la branche pour que vous puissiez revenir plus tard. Supprimer supprime le répertoire worktree et sa branche, ainsi que tout le travail qu’ils contiennent
• L’état du worktree ne peut pas être vérifié : quand Claude Code ne peut pas compter les modifications du worktree ou ne peut pas inspecter les extraits de ses sous-modules, il vous demande plutôt que de supprimer le worktree automatiquement. L’invite nomme ce qu’il n’a pas pu vérifier

​

Reprendre une session worktree

• Répertoire de lancement : reprenez à partir de l’extraction principale ou d’un autre répertoire du dépôt. Claude Code réentre dans un worktree qu’il a créé avec git sous .claude/worktrees/ même quand vous lancez depuis l’intérieur. Quand vous lancez depuis l’intérieur de tout autre worktree, Claude Code ne le réentre que s’il peut le justifier de là : un worktree qui est son propre dépôt, un sans métadonnées git, ou un lancement depuis un sous-répertoire d’un worktree que vous avez créé avec git worktree add refuse, donc lancez ceux-ci depuis l’extraction principale.
• --fork-session : la session dupliquée commence dans le répertoire à partir duquel vous avez lancé Claude, et Claude Code laisse le worktree de la session d’origine intact.
• Worktree supprimé : si le répertoire worktree n’existe plus, Claude Code reprend la session dans le répertoire à partir duquel vous avez lancé Claude. Il vous dit que le worktree est parti et efface la liaison du worktree de la session.

​

Comment Claude Code applique l’isolation

• Modifications de fichiers : Claude Code bloque une Edit, Write, ou NotebookEdit qui cible un chemin dans l’extraction principale.
• Répertoire de travail de la commande : Claude Code bloque une commande Bash, PowerShell, ou Monitor dont le répertoire de travail se résout à l’extraction principale, ou dont le répertoire de travail il ne peut pas vérifier reste en dehors.
• Redirections Git : Claude Code bloque une commande Bash ou Monitor qui redirige git vers l’extraction principale. La redirection peut provenir de git -C, --git-dir, une variable GIT_DIR ou GIT_WORK_TREE, ou un cd dans l’extraction principale avant d’exécuter git.
• Forme de la commande : Claude Code bloque une commande Bash ou Monitor quand il ne peut pas vérifier à partir du texte de la commande que tout git que la commande exécute reste à l’intérieur du worktree. Cela se produit, par exemple, quand le nom de la commande est calculé à l’exécution, quand la syntaxe ne peut pas être analysée, ou quand une expansion telle que ${!name} ou ${ command; } pourrait exécuter une commande que le texte ne précise pas. Claude Code indique à Claude comment réécrire la commande refusée, par exemple en la divisant en commandes simples et séparées. Vous ne pouvez pas désactiver cette vérification.

​

Isoler les subagents avec worktrees

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

​

Nettoyer les worktrees des subagents et des sessions en arrière-plan

• Le worktree contient toujours du travail : fichiers modifiés ou non suivis, ou commits non poussés.
• Un sous-module extrait dans le worktree contient des fichiers modifiés ou non suivis, ou Claude Code ne peut pas inspecter les sous-modules du worktree. Cette vérification nécessite Claude Code v2.1.274 ou une version ultérieure.
• L’un des quatre cas qui bloquent également la création de worktree s’applique : Claude Code ne peut pas déterminer quels pilotes de filtre la configuration du dépôt définit, ou y trouve un paramètre qu’il ne peut pas désactiver.
• Le worktree appartient à une session --worktree que vous n’avez pas mise en arrière-plan, quel que soit son âge.
• Vous avez créé le worktree vous-même avec git worktree add, même si vous avez ensuite exécuté une session --worktree <name> dedans et l’avez mise en arrière-plan.

​

Personnaliser la création de worktrees

​

Choisir la branche de base

• "fresh" (par défaut) : se ramifie à partir de la branche par défaut du dépôt sur la télécommande, généralement main, pour que le worktree commence à partir d’un arbre propre correspondant à la télécommande.
• "head" : se ramifie à partir de votre HEAD local actuel, pour que le worktree porte vos commits non poussés et l’état de la branche de fonctionnalité. Utilisez ceci lors de l’isolation des subagents qui doivent opérer sur un travail en cours. À l’intérieur d’un worktree, "head" se résout en HEAD de ce worktree, pas en celui de l’extraction principale.

{
  "worktree": {
    "baseRef": "head"
  }
}

​

Se ramifier à partir d’une demande de tirage

claude --worktree "#1234"

• github.com : récupère pull/<number>/head
• gitlab.com : récupère merge-requests/<number>/head
• GitHub Enterprise, GitLab auto-hébergé, ou tout autre hôte : essaie d’abord pull/<number>/head, puis merge-requests/<number>/head

​

Copier les fichiers gitignorés dans les worktrees

.env
.env.local
config/secrets.json

​

Réutiliser un nom de worktree

• Il n’a pas de modifications non validées ou de fichiers non suivis.
• Il est toujours sur la branche que Claude Code a créée pour lui.
• Il n’a pas de commits propres, ou sa demande de tirage ou de fusion a été fusionnée et sa branche distante supprimée.

• Le worktree échoue l’une des conditions.
• Claude Code ne peut pas vérifier l’état du worktree.
• worktree.baseRef est "head".
• Le nom est une référence de demande de tirage ou de fusion.

​

Remplacer la création de worktree par un hook

​

Ce que les worktrees partagent avec l’extraction principale

• Le répertoire .git du dépôt : les commandes git dans un worktree écrivent dans le répertoire .git partagé du dépôt principal, et l’isolation du système de fichiers permet ces écritures, donc les commandes telles que git commit fonctionnent depuis l’intérieur d’un worktree avec le sandbox activé.
• Plugins : les plugins installés à portée du projet à partir de l’extraction principale se chargent également dans les worktrees du même dépôt, vous n’avez donc pas besoin de les réinstaller par worktree. Nécessite Claude Code v2.1.200 ou ultérieur.
• Approbations de permission : choisir « Oui, et ne plus demander » pour une commande Bash dans une session worktree sauvegarde la règle dans le .claude/settings.local.json de l’extraction principale, pour qu’elle s’applique dans l’extraction principale et dans chaque autre worktree du dépôt, et qu’elle survive à la suppression du worktree. Sur Windows et dans les autres cas où Claude Code n’utilise pas la racine du dépôt, la règle reste avec ce worktree. Avant la v2.1.211, une approbation accordée dans un worktree était sauvegardée à l’intérieur de ce worktree, ne s’appliquait pas ailleurs, et était perdue quand le worktree était supprimé. Voir où les approbations sont sauvegardées.
• Compétences, agents et commandes non suivis : quand l’extraction du worktree n’a pas de répertoire .claude/skills à sa racine, par exemple parce que votre .claude/skills est gitignored, Claude Code charge les compétences du projet de l’extraction principale dans la session worktree. Dans un worktree avec son propre répertoire .claude/skills, seule cette copie se charge. La même lecture couvre .claude/agents et .claude/commands. Pour les compétences, la lecture nécessite Claude Code v2.1.277 ou ultérieur.

​

Gérer les worktrees manuellement

git worktree add ../project-feature-a -b feature-a

git worktree add ../project-bugfix fix-issue-456

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

Contrôle de version non-git

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

​

Dépannage

​

Claude Code ne peut pas entrer dans le worktree au démarrage

​

La création de worktree échoue sur un chemin symlinké

​

Les fichiers Git LFS sont des fichiers pointeurs dans un worktree que Claude Code a créé

• Could not read the repository git config to neutralize filter drivers : Claude Code n’a pas pu lire le .git/config du dépôt, par exemple à cause de ses permissions. Corrigez cela et réessayez.
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline) : renommez ou supprimez ce pilote de filtre dans .git/config et réessayez.
• The repository git config has a conditional include (includeIf) : déplacez les paramètres que l’includeIf dans .git/config récupère directement dans ce fichier, supprimez l’includeIf, et réessayez. Un includeIf dans votre config git global ne déclenche pas ceci.
• Git was not run: the repository's own git config sets <key> : le message nomme une clé qui pointe Git LFS vers un programme à exécuter, comme lfs.customtransfer.<name>.path ou lfs.standalonetransferagent. Si ce paramètre est le vôtre, déplacez-le vers votre config git global. Si vous ne le reconnaissez pas, supprimez-le du config git du dépôt, puisqu’un outil ou checkout auquel vous ne faites pas confiance peut l’avoir écrit. Réessayez une fois que la clé est partie du config du dépôt.

​

Claude Code refuse d’utiliser un worktree

• Dit launch from the parent checkout ou Run the resume from the project checkout : vous avez lancé Claude Code depuis l’intérieur du worktree. Lancez à partir de l’extraction principale à la place ; le worktree n’a pas besoin de recréation.
• Dit it cannot be resumed or re-entered : rien dans cette session ne justifie le worktree à partir d’où vous avez lancé. Recréez-le ; le répertoire et son travail restent sur le disque pour récupération manuelle, et quand le worktree a une extraction parente, la reprise de là fonctionne aussi.
• Dit it contains the protected checkout : le répertoire refusé est un parent de votre extraction principale, comme votre répertoire personnel. Ne le supprimez pas. Changez le chemin du worktree, comme le chemin que votre hook WorktreeCreate retourne ou la cible EnterWorktree, pour que le worktree ne contienne pas l’extraction.
• Dit the protected checkout <path> has a .git entry that could not be examined ou has git metadata that could not be resolved : le problème est les métadonnées git de l’extraction principale, pas celles du worktree. Ne supprimez pas le worktree, et ignorez les conseils de fin du message pour le recréer, qui ne s’appliquent pas à ces deux fins. Réparez l’extraction principale, par exemple un problème de permissions ou un refus git dubious ownership sur son .git, et réessayez.
• Dit its recorded path has a network spelling : Claude Code ne reprend jamais dans un worktree à un chemin réseau. Recréez le worktree à un chemin local.
• Toute autre fin : le message nomme le problème et sa correction, comme supprimer une redirection core.worktree ou recréer le worktree ; suivez-le. Avant de supprimer un répertoire dont le message dit que son identité git n’a pas pu être vérifiée, adressez d’abord la cause nommée, par exemple un lien symbolique dans le chemin du worktree ou git lui-même échouant à s’exécuter, puisque le répertoire peut être sain. Quand vous recréez, sauvegardez tous les changements dont vous avez besoin à partir de l’ancien répertoire d’abord ; il reste sur le disque.

​

La session reprend en dehors de son worktree

• Error: cannot resume into worktree <path>: ...This session was not started. pour un refus que le tableau montre comme Did not re-enter. Claude Code efface la liaison du worktree avant de quitter, et l’erreur le dit ; la prochaine fois que vous reprenez la conversation, la session continue dans le répertoire actuel sans isolation de worktree. Avant la v2.1.260, Claude Code n’écrivait pas la liaison effacée, donc chaque nouvelle tentative de la même reprise échouait avec la même erreur. Si vous supprimez les écritures de transcription, l’effacement ne peut pas être sauvegardé. L’erreur dit alors que la même commande sera refusée à nouveau, et nomme --fork-session et le démarrage d’une nouvelle conversation comme des façons de continuer sans le worktree.
• Error: could not verify worktree <path> for this resume, so the resume was aborted... pour Could not verify
• Error: ...The worktree binding is kept. pour Could not re-enter
• Notice: the worktree <path> for this session no longer exists... pour un worktree disparu ; Claude Code l’imprime et continue la session, comme une reprise interactive le fait

​

Voir aussi

• Subagents : déléguer le travail à des agents isolés dans une session
• Messagerie entre sessions : laisser les sessions dans vos worktrees se transmettre les résultats
• Équipes d’agents : coordonner plusieurs sessions Claude automatiquement
• Gérer les sessions : nommer, reprendre et basculer entre les conversations
• Sessions parallèles de bureau : sessions soutenues par worktree dans l’application de bureau