Exécuter des sessions parallèles avec worktrees

Isolez les sessions Claude Code parallèles dans des git worktrees séparés pour que les modifications ne se heurtent pas. Couvre le flag --worktree, l'isolation des subagents, .worktreeinclude, le nettoyage et les hooks VCS non-git.

Un git worktree est un répertoire de travail séparé avec ses propres fichiers et branche, partageant le même historique de dépôt et la même télécommande que votre extraction principale. Exécuter chaque session Claude Code dans son propre worktree signifie que les modifications dans une session ne touchent jamais les fichiers d'une autre, vous pouvez donc avoir Claude construisant une fonctionnalité dans un terminal tout en corrigeant un bug dans un second.

Cette page couvre l'isolation des worktrees dans la CLI. Tout ce qui suit suppose un dépôt git. Pour les autres systèmes de contrôle de version, voir Contrôle de version non-git. L'application de bureau crée automatiquement un worktree pour chaque nouvelle session.

Les worktrees sont l'une des plusieurs façons d'exécuter Claude en parallèle. Ils isolent les modifications de fichiers, tandis que les subagents et les équipes d'agents coordonnent le travail lui-même. Voir Exécuter les agents en parallèle pour comparer les approches, ou passez directement à Isoler les subagents avec worktrees pour utiliser les worktrees et les subagents ensemble.

Démarrer Claude dans un worktree

Passez --worktree ou -w pour créer un worktree isolé et démarrer Claude dedans. Par défaut, le worktree est créé sous .claude/worktrees/<value>/ à la racine de votre dépôt, sur une nouvelle branche nommée worktree-<value> :

claude --worktree feature-auth

Pour placer les worktrees ailleurs, configurez un hook WorktreeCreate. Exécutez la commande à nouveau avec un nom différent dans un autre terminal pour démarrer une deuxième session isolée :

claude --worktree bugfix-123

Si vous omettez le nom, Claude en génère un tel que bright-running-fox :

claude --worktree

Vous pouvez également demander à Claude de « travailler dans un worktree » pendant une session, et il en créera un avec l'outil EnterWorktree. Une fois dans un worktree, Claude peut basculer directement vers un autre sous .claude/worktrees/ en appelant EnterWorktree avec le chemin cible. Le worktree précédent reste sur le disque intact.

Avant d'utiliser --worktree de manière interactive dans un répertoire pour la première fois, acceptez la boîte de dialogue de confiance de l'espace de travail en exécutant claude une fois dans ce répertoire. Si la confiance n'a pas encore été acceptée, --worktree se termine avec une erreur et vous invite à exécuter claude dans le répertoire en premier. Les exécutions non interactives avec -p ignorent la vérification de confiance, donc claude -p --worktree procède sans elle.

Choisir la branche de base

Les worktrees se ramifient à partir de la branche par défaut de votre dépôt, origin/HEAD, ils commencent donc à partir d'un arbre propre correspondant à la télécommande. Si aucune télécommande n'est configurée ou si la récupération échoue, le worktree revient à votre HEAD local actuel. Pour toujours vous ramifier à partir du HEAD local à la place, définissez worktree.baseRef sur "head" dans paramètres. Définir baseRef sur "head" fait que les nouveaux worktrees portent vos commits non poussés et l'état de la branche de fonctionnalité, ce qui est utile lors de l'isolation des subagents qui doivent opérer sur un travail en cours. Le paramètre n'accepte que "fresh" ou "head", pas des refs git arbitraires :

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

Pour vous ramifier à partir d'une demande de tirage spécifique, passez le numéro de PR préfixé par #, ou une URL complète de demande de tirage GitHub. Claude Code récupère pull/<number>/head à partir de origin et crée le worktree à .claude/worktrees/pr-<number> :

claude --worktree "#1234"

Pour un contrôle total sur la façon dont les worktrees sont créés, configurez un hook WorktreeCreate, qui remplace entièrement la logique git worktree par défaut.

Copier les fichiers gitignorés dans les worktrees

Un worktree est une extraction fraîche, donc les fichiers non suivis comme .env ou .env.local de votre dépôt principal ne sont pas présents. Pour les copier automatiquement quand Claude crée un worktree, ajoutez un fichier .worktreeinclude à la racine de votre projet.

Le fichier utilise la syntaxe .gitignore. Seuls les fichiers qui correspondent à un motif et sont également gitignorés sont copiés, donc les fichiers suivis ne sont jamais dupliqués.

Ce .worktreeinclude copie deux fichiers env et une configuration de secrets dans chaque nouveau worktree :

.env
.env.local
config/secrets.json

Cela s'applique aux worktrees créés avec --worktree, worktrees de subagents, et aux sessions parallèles dans l'application de bureau.

Isoler les subagents avec worktrees

Les subagents peuvent s'exécuter dans leurs propres worktrees pour que les modifications parallèles ne se heurtent pas. Demandez à Claude d'« utiliser les worktrees pour vos agents », ou définissez-le de manière permanente sur un subagent personnalisé en ajoutant isolation: worktree au frontmatter. Chaque subagent obtient un worktree temporaire qui est supprimé automatiquement quand le subagent se termine sans modifications.

Les worktrees des subagents utilisent la même branche de base que --worktree, donc ils se ramifient à partir de la branche par défaut de votre référentiel sauf si worktree.baseRef est défini sur "head".

Nettoyer les worktrees

Quand vous quittez une session worktree, le nettoyage dépend de si vous avez apporté des modifications :

• Pas de modifications non validées, pas de fichiers non suivis et pas de nouveaux commits : le worktree et sa branche sont supprimés automatiquement. Si la session a un nom, Claude vous demande plutôt de conserver le worktree pour plus tard
• Des modifications non validées, des fichiers non suivis ou de nouveaux commits existent : 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, en supprimant toutes les modifications non validées, les fichiers non suivis et les commits
• Exécutions non interactives : les worktrees créés avec --worktree aux côtés de -p ne sont pas nettoyés automatiquement puisqu'il n'y a pas d'invite de sortie. Supprimez-les avec git worktree remove

Les worktrees que Claude a créés pour les subagents et les sessions en arrière-plan sont supprimés automatiquement une fois qu'ils sont plus anciens que votre paramètre cleanupPeriodDays, à condition qu'ils n'aient pas de modifications non validées, pas de fichiers non suivis et pas de commits non poussés. Les worktrees que vous créez avec --worktree ne sont jamais supprimés par ce balayage.

Pendant qu'un agent s'exécute, Claude exécute git worktree lock sur son worktree pour que le nettoyage concurrent ne puisse pas le supprimer. Le verrou est libéré quand l'agent se termine. Pour nettoyer un worktree que le balayage conserve, exécutez git worktree remove, en ajoutant --force si le worktree a des modifications non validées ou des fichiers non suivis.

Gérer les worktrees manuellement

Pour un contrôle total sur l'emplacement du worktree et la configuration de la branche, créez des worktrees directement avec Git. Ceci est utile quand vous devez extraire une branche existante spécifique ou placer le worktree en dehors du dépôt.

Créer un worktree sur une nouvelle branche :

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

Créer un worktree à partir d'une branche existante :

git worktree add ../project-bugfix bugfix-123

Démarrer Claude dans le worktree :

cd ../project-feature-a && claude

Lister vos worktrees :

git worktree list

Supprimer un quand vous en avez terminé :

git worktree remove ../project-feature-a

Voir la documentation Git worktree pour la référence complète des commandes. N'oubliez pas d'initialiser votre environnement de développement dans chaque nouveau worktree : installez les dépendances, configurez les environnements virtuels, ou exécutez tout ce que votre configuration de projet nécessite.

Contrôle de version non-git

L'isolation des worktrees utilise git par défaut. Pour SVN, Perforce, Mercurial ou d'autres systèmes, configurez les hooks WorktreeCreate et WorktreeRemove pour fournir une logique de création et de nettoyage personnalisée. Parce que le hook remplace le comportement git par défaut, .worktreeinclude n'est pas traité quand vous utilisez --worktree. Copiez plutôt tous les fichiers de configuration locale à l'intérieur de votre script de hook.

Ce hook WorktreeCreate lit le nom du worktree à partir de stdin, extrait une copie de travail SVN fraîche, et imprime le chemin du répertoire pour que Claude Code puisse l'utiliser comme répertoire de travail de la session :

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

Associez-le à un hook WorktreeRemove pour nettoyer quand la session se termine. Voir la référence des hooks pour le schéma d'entrée et un exemple de suppression.

Voir aussi

Les worktrees gèrent l'isolation des fichiers. Les pages connexes ci-dessous couvrent la délégation du travail dans ces extractions isolées et le basculement entre les sessions que vous créez :

• Subagents : déléguer le travail à des agents isolés dans une session
• É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