Git worktree dans Claude Code : sessions parallèles

Des informations pratiques sur l’utilisation d’Ailoot sont disponibles dans la documentation.

Qu’est-ce qu’un git worktree dans Claude Code ?#

Lancer plusieurs agents en parallèle dans le même dossier, c’est le problème fondamental du vibe-coding au rythme de 2026. Les agents d’IA écrivent du code plus vite qu’une personne ne peut suivre qui modifie quoi. Sans isolation des fichiers, lancer deux sessions Claude Code en parallèle dans un même répertoire se termine par l’écrasement du travail de l’une par l’autre.

Git worktree règle ce problème au niveau du système de fichiers. Tu as un répertoire principal dans lequel tu travailles. La commande claude --worktree feature-auth crée le dossier .claude/worktrees/feature-auth/ sur une branche distincte et y lance Claude Code. Les fichiers sont isolés. Les changements d’une session ne sont pas visibles dans l’autre tant que tu ne les as pas explicitement fusionnés.

La documentation officielle d’Anthropic le formule ainsi :

Un indice pour faire le point : si tu as déjà reçu un commit dont la moitié des fichiers correspondait au travail de quelqu’un d’autre, tu as besoin d’un worktree.

En quoi git worktree diffère-t-il d’une branche classique ?#

Le flux Git standard : tu es sur la branche main et exécutes git checkout feature-x — Git écrase les fichiers de la copie de travail. Un npm run dev en cours d’exécution cesse de fonctionner parce que package.json a changé sous ses yeux. Tu mets tes changements non commités en stash et attends que l’IDE réindexe. Tu reviens en arrière et tout est de nouveau écrasé ; tu dois donc refaire un stash et un pop.

Git worktree offre une autre possibilité : au lieu de basculer un dossier entre les branches, tu crées un deuxième dossier pour une autre branche. La commande git worktree add ../project-feature-x feature-x crée le répertoire ../project-feature-x/ avec les fichiers de la branche feature-x. Ta branche main reste dans le dossier d’origine et le serveur de développement continue de fonctionner.

Auparavant, le mode worktree dans Claude Code devait être configuré manuellement : git worktree add, puis cd, puis claude — et il fallait répéter ces étapes dans chaque terminal. L’option --worktree (également -w) fait les trois en une seule commande.

Lancer la première session parallèle : l’option --worktree#

Exemple minimal. Ouvre le premier terminal à la racine du projet :

claude --worktree feature-auth

Claude Code effectue trois opérations :

1. Crée .claude/worktrees/feature-auth/ avec un instantané de origin/HEAD (généralement ta branche par défaut).
2. Crée une nouvelle branche worktree-feature-auth.
3. Lance la session dans ce dossier.

Ouvre un deuxième terminal à la racine du même dépôt :

claude --worktree bugfix-123

Et voilà. Deux sessions Claude Code, des fichiers différents sur le disque, des branches Git différentes. Si tu écris le code de l’authentification dans la première et corriges un test qui échoue dans la deuxième, elles ne peuvent physiquement pas se gêner.

Si tu ne veux pas saisir de nom, Claude en trouvera un :

claude --worktree
# → creates something like .claude/worktrees/bright-running-fox/

Un conseil pour les débutants en Git : ajoute .claude/worktrees/ à .gitignore. Sinon, lorsque tu exécutes git status dans le dossier principal, tu verras le contenu de tous les worktrees comme des fichiers non suivis :

# .gitignore
.claude/worktrees/

Piège à éviter : avant le premier lancement de --worktree dans un nouveau répertoire, ouvre-le avec un claude classique (sans l’option) et accepte la boîte de dialogue de confiance de l’espace de travail. Sinon, l’option échoue avec une erreur « trust not accepted », y compris si tu la combines avec -p en mode headless.

Où se trouvent les worktrees et comment les trouver#

L’emplacement par défaut est fixe : .claude/worktrees/<value>/ à la racine du dépôt. Si ton projet se trouve dans ~/dev/my-app/, le worktree feature-auth sera dans ~/dev/my-app/.claude/worktrees/feature-auth/.

Pour les configurations non standard (par exemple, si tu veux placer le worktree en dehors du dépôt), il existe le hook WorktreeCreate — nous y reviendrons dans la section sur SVN et Mercurial.

Au sein d’une session Claude, tu peux passer à un autre worktree existant. Dis simplement dans la conversation : « switch to .claude/worktrees/bugfix-123 », et Claude appellera l’outil EnterWorktree. Le dossier actuel restera intact ; tu pourras revenir de la même façon.

La commande Git standard affiche la liste de tous les worktrees, y compris le principal et ceux créés manuellement :

git worktree list

Le résultat ressemblera à ceci :

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Copier .env et les secrets : le fichier .worktreeinclude#

Quand --worktree crée un nouveau dossier, celui-ci ne contient que ce qui a été committé dans Git. .env, qui contient les clés API, et .env.local, qui contient la configuration locale, figurent dans .gitignore et ne se trouvent donc pas dans le worktree. Le tout premier npm run dev échoue alors avec « MISSING DATABASE_URL ».

La solution artisanale consiste à copier manuellement .env après chaque --worktree. Ça marche une fois, puis on oublie. La solution d’Anthropic consiste à créer un fichier .worktreeinclude à la racine du projet, qui répertorie les fichiers ignorés par Git à copier automatiquement dans chaque nouveau worktree.

Crée un fichier .worktreeinclude à la racine du dépôt :

.env
.env.local
config/secrets.json

La syntaxe est la même que celle de .gitignore. Tu peux utiliser des motifs glob :

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic énonce une règle claire pour éviter les accidents :

Autrement dit, tu ne peux pas copier accidentellement package.json avec .worktreeinclude : il ne figure pas dans .gitignore. Tu peux y mettre tous les motifs que tu veux sans risque.

Le même fichier .worktreeinclude fonctionne dans trois modes : --worktree manuel, les worktrees automatiques pour les subagents (voir ci-dessous) et les sessions de l’application de bureau Claude.

Créer un worktree à partir d’une pull request pour une revue de code#

Scénario classique de revue de code : un collègue t’a envoyé une PR ; tu dois examiner le code, lancer des tests et laisser un commentaire. Avec un git checkout pull/1234/head classique, tu bascules une nouvelle fois la copie de travail et interromps ta session active.

Avec l’option --worktree, une seule commande suffit :

claude --worktree "#1234"

Voici ce qui se passe : Claude Code exécute git fetch origin pull/1234/head, crée un worktree dans .claude/worktrees/pr-1234/ et récupère la branche de la PR. La session démarre. Tu peux immédiatement lui demander de « lire le diff, lancer les tests et rechercher les erreurs de logique » ; pendant que Claude travaille, ta session principale sur main continue de fonctionner.

L’autre syntaxe possible est l’URL complète de la pull request :

claude --worktree https://github.com/OWNER/REPO/pull/1234

Dans un vrai projet, associer claude --worktree "#N" à ton propre subagent chargé des revues de code permet d’obtenir une revue automatique en une ou deux minutes. Lance-le en arrière-plan, poursuis ton travail dans la fenêtre principale et consulte le résultat avec claude agents.

Branche de base : worktree.baseRef avec fresh ou head#

Par défaut, chaque nouveau worktree part de origin/HEAD. L’avantage est de partir d’une base propre qui correspond avec certitude à ce que verra l’intégration continue. L’inconvénient, c’est que si tu as des changements non commités ou plusieurs commits locaux au-delà de la version distante sur ta branche actuelle, ils ne seront pas inclus dans le nouveau worktree.

Pour démarrer depuis ton commit HEAD local actuel, ajoute ceci à .claude/settings.json ou aux paramètres globaux :

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

Désormais, claude --worktree experimental-feature part du HEAD local actuel. Cela convient aux fonctionnalités ayant des commits locaux non poussés, sans inclure les modifications suivies encore non commitées. Si le sous-agent en a besoin, préserve-les, transfère-les explicitement et inspecte le diff cible. Ne confonds pas ce transfert avec .worktreeinclude, qui traite les fichiers locaux ignorés.

Le paramètre accepte exactement deux valeurs : "fresh" (= origin/HEAD) et "head" (= le HEAD local). Les références arbitraires comme "feature-branch" ou un hash de commit ne sont pas acceptées : cette restriction est délibérée et évite une explosion combinatoire des options.

Isoler automatiquement les subagents : isolation: worktree#

Quand tu dis à Claude « lance trois subagents : l’un examine la base de données, le deuxième regarde l’API et le troisième vérifie les tests », tous les trois travaillent par défaut dans ta copie de travail. Si deux d’entre eux seulement modifient le même fichier au même moment, un conflit survient. La solution consiste à attribuer automatiquement un worktree à chacun.

Méthode 1 : le demander à l’oral. Écris à Claude dans la conversation :

Utilise des worktrees pour tes agents.

Claude appliquera l’isolation à tous les subagents lancés par la suite dans cette session.

Méthode 2 : le définir explicitement dans le subagent lui-même. Dans le fichier du subagent (par exemple, .claude/agents/code-reviewer.md), ajoute un champ au frontmatter :

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

Tu es un réviseur méticuleux. Lis le diff et recherche les erreurs de logique...

Désormais, chaque lancement de ce subagent reçoit un worktree temporaire dans .claude/worktrees/. Si le subagent n’a rien écrit, le dossier est automatiquement supprimé à la fin. S’il reste des changements non commités, Claude te demandera si tu veux les conserver ou les supprimer.

La branche de base des worktrees de subagents est la même que pour --worktree : par défaut, origin/HEAD ; avec worktree.baseRef: head, le HEAD local.

Matrice de décision : worktree, /bg, subagent ou Agent View#

Combinaisons courantes :

• « 2 fonctionnalités en parallèle, manuellement » — deux terminaux, chacun exécutant claude --worktree. Le cas le plus simple.
• « Lance une refactorisation pendant la nuit ; je ferme l’application » — /bg + /goal avec une condition d’achèvement. La session fonctionne indépendamment de ta fenêtre.
• « Un prompt, trois recherches en parallèle » — trois subagents avec isolation: worktree. Chacun dans son propre bac à sable.
• « Qu’est-ce qui tourne en ce moment ? » — claude agents. Un tableau de bord de toutes les sessions avec les filtres « running », « blocked » et « done ».

5 pièges à éviter avec les worktrees#

1. Worktree lancé, .env manquant, rien ne fonctionne. Le problème le plus courant. Un worktree est un nouveau checkout sans les fichiers ignorés par Git. Dès que tu configures le mode worktree, ajoute un fichier .worktreeinclude avec .env* et les configurations locales nécessaires. Vérifie que le fichier se trouve à la racine du dépôt, et non dans .claude/.

2. Tu veux revenir à la branche principale, exécutes cd vers la racine et perds tes changements non commités dans le worktree. Le dossier racine et le worktree sont deux copies de travail différentes. Tu es revenu avec cd ; les changements dans le worktree sont restés sur place, ils ne sont pas partis. Mais si tu t’es trompé et as exécuté git stash dans le dossier principal en pensant être dans le worktree, le stash sera créé sur la branche principale et non sur celle à laquelle tu t’attendais.

3. Tu as lancé 5 sessions en parallèle et ne te souviens plus de ce que fait chacune. La documentation d’Anthropic avertit explicitement que la plupart des développeurs ne peuvent pas gérer cognitivement plus de 2–3 sessions. Un signe de surcharge : ouvrir Agent View et ne pas pouvoir dire immédiatement ce que fait chaque agent. Limite-toi à deux sessions simultanées. Si la tâche en exige davantage, elle devrait être orchestrée avec /goal + des subagents, plutôt que manuellement.

4. Les worktrees lancés avec -p (mode headless) ne sont pas nettoyés automatiquement. La commande claude --worktree feature-x -p "do thing" n’affiche pas de demande interactive à la fermeture ; Claude ne te demande donc jamais « supprimer le worktree ? ». Ces worktrees s’accumulent. Nettoie-les manuellement : git worktree remove .claude/worktrees/feature-x. Tu peux aussi utiliser un script cron qui supprime tout ce qui date de plus de 7 jours.

5. Boîte de dialogue de confiance dans un nouveau dossier. Si tu ouvres le dépôt pour la première fois et exécutes immédiatement claude --worktree, la commande échouera. Exécute claude sans options, accepte la confiance de l’espace de travail et quitte ; --worktree fonctionnera ensuite. C’est intentionnel, afin que Claude n’accède pas au projet de quelqu’un d’autre sans le consentement de l’utilisateur.

Nettoyage : ce qui est supprimé automatiquement#

La logique de nettoyage dépend de ce que tu as fait dans le worktree et de la façon dont tu as lancé la session. La documentation d’Anthropic énumère trois scénarios :

Scénario 1 : tu es entré, n’as rien fait et es ressorti — le worktree a été supprimé.

Scénario 2 : tu as travaillé sans committer — à la fermeture, Claude te demandera « conserver ou supprimer ? ». « Conserver » garde le dossier et la branche pour plus tard. « Supprimer » efface le répertoire ainsi que les changements non commités et les nouveaux commits. C’est destructif : ne clique pas sur « supprimer » par habitude.

Scénario 3 : tu as lancé la commande avec -p (mode headless), puis elle s’est terminée. Le worktree reste présent. Nettoie-le manuellement :

git worktree remove .claude/worktrees/feature-x

En outre, le nettoyage en arrière-plan supprime automatiquement les worktrees issus de subagents et de sessions /bg s’ils sont plus anciens que cleanupPeriodDays jours (un paramètre généralement défini sur 30 jours par défaut) et ne contiennent aucun travail non enregistré. Les worktrees de --worktree ne sont pas touchés par le nettoyage automatique : ils sont sous ta responsabilité.

Alternatives pour SVN, Perforce et Mercurial : le hook WorktreeCreate#

Si le dépôt utilise Subversion ou Mercurial, l’option --worktree ne fonctionnera pas directement. Anthropic propose un point d’extension au moyen de deux hooks : WorktreeCreate (crée une copie isolée) et WorktreeRemove (la supprime).

Exemple de hook SVN tiré de la documentation officielle :

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

Le hook lit le nom du worktree depuis stdin ({ "name": "feature-auth" }), exécute svn checkout dans un répertoire prédéfini et affiche le chemin sur stdout ; Claude Code l’utilise comme répertoire de travail de la nouvelle session.

Point important : lorsque tu utilises ton propre hook, .worktreeinclude n’est pas utilisé. Si tu as besoin de .env ou d’autres fichiers ignorés par Git dans le nouveau dossier, copie-les dans le script du hook lui-même.

Pour la suite : trois mécanismes de parallélisme connexes#

Worktree fournit l’isolation des fichiers. /bg fournit l’isolation du contexte. Les subagents fournissent l’isolation des tâches. Chaque mécanisme résout un problème à lui seul. Ensemble, ils permettent de mener trois à cinq tâches en parallèle sans surcharge cognitive. Ce sont les compétences qui sous-tendent le vibe-coding avancé en 2026.

Ce sujet se prolonge naturellement par trois sujets connexes : comment configurer un agent autonome à l’aide de /goal et d’Agent View, comment créer tes propres subagents pour tes tâches et comment lancer des centaines d’agents avec Dynamic Workflows.

Ouvrir Ailoot.