Claude Code Worktrees :
sessions parallèles sans conflit
Travaillez sur plusieurs fonctionnalités en simultané avec des git worktrees isolés. Chaque session Claude Code dans son propre environnement de développement.
Les worktrees de Claude Code permettent d’exécuter plusieurs sessions IA en parallèle, chacune isolée dans sa propre branche git. Depuis la version 2.1.49 de février 2026, le flag --worktree ou -w crée automatiquement un répertoire de travail séparé pour chaque session Claude Code.
Cette isolation native évite les conflits de fichiers quand vous travaillez sur plusieurs features ou bugfixes simultanément. Chaque worktree partage l’historique git du dépôt mais possède ses propres fichiers et sa propre branche de développement.
La première fois que j’ai voulu faire deux modifications en parallèle avec Claude Code, j’ai perdu 20 minutes de travail. Une session avait écrasé les changements de l’autre. J’ai cherché une solution et découvert les worktrees natifs qui ont changé ma façon de travailler.
Dans ce guide complet, je vous montre comment j’utilise les worktrees au quotidien pour jongler entre features, bugfixes et expérimentations. Vous verrez comment configurer le flag -w, gérer les fichiers .env et secrets, et nettoyer proprement vos worktrees une fois le travail terminé.
Qu’est-ce qu’un worktree dans Claude Code ?
Un git worktree est un répertoire de travail séparé qui partage le même dépôt git que votre checkout principal. Il possède ses propres fichiers et sa propre branche, mais l’historique des commits reste commun entre tous les worktrees du projet. Quand vous modifiez des fichiers dans un worktree, cela n’affecte absolument pas votre répertoire principal ni les autres worktrees.
Claude Code exploite cette fonctionnalité git native pour isoler ses sessions de développement de manière transparente. Chaque session dans un worktree peut modifier des fichiers, créer des commits, tester des implémentations, sans interférer avec les autres sessions en cours. C’est particulièrement utile quand vous travaillez sur plusieurs tâches en parallèle avec l’IA.
Par défaut, les worktrees Claude Code sont créés dans le dossier .claude/worktrees/ à la racine de votre dépôt. Chaque worktree obtient une nouvelle branche nommée worktree-<nom> basée sur origin/HEAD. Cette organisation permet de retrouver facilement vos sessions et de basculer entre elles.
L’isolation fonctionne aussi pour les subagents que Claude peut déléguer. Quand Claude confie une tâche à un agent secondaire, celui-ci peut travailler dans son propre worktree temporaire. Les modifications sont ainsi compartimentées jusqu’à validation finale, évitant tout risque de conflit entre agents.
Comment démarrer une session avec le flag -w ?
La syntaxe est simple et intuitive : ajoutez --worktree ou -w suivi d’un nom pour créer un worktree dédié. Claude Code crée automatiquement le répertoire, la branche git, et démarre la session dans cet environnement isolé. Tout est transparent pour vous.
Si vous omettez le nom, Claude génère un identifiant aléatoire comme bright-running-fox ou calm-dancing-bear. Je préfère toujours nommer mes worktrees explicitement pour les retrouver facilement. Un nom comme feature-auth ou bugfix-123 indique clairement le contexte de travail.
Vous pouvez aussi créer un worktree à partir d’une pull request existante. Passez le numéro de PR préfixé par # et Claude Code fetch la branche correspondante depuis le remote. C’est pratique pour reviewer du code ou contribuer à une PR en cours sans polluer votre branche locale.
Une fois dans le worktree, Claude Code fonctionne exactement comme d’habitude. La seule différence est que les fichiers sont dans un répertoire séparé. Vous pouvez ouvrir un second terminal et lancer un autre worktree pour travailler sur une tâche différente.
Comment gérer les fichiers .env et secrets dans les worktrees ?
Les fichiers non versionnés comme .env, .env.local ou config/secrets.json ne sont pas présents dans un nouveau worktree. C’est un checkout frais qui ne contient que les fichiers trackés par git. Sans configuration spécifique, votre application ne démarrera pas correctement car les variables d’environnement seront manquantes.
La solution élégante est le fichier .worktreeinclude à la racine de votre projet. Il utilise la syntaxe gitignore pour lister les fichiers à copier automatiquement dans chaque nouveau worktree. C’est une whitelist de fichiers locaux à dupliquer.
Attention au fonctionnement : seuls les fichiers qui matchent un pattern ET qui sont également gitignorés seront copiés. Les fichiers trackés par git ne sont jamais dupliqués pour éviter les incohérences. Cela garantit que vous ne copiez que les vrais fichiers locaux.
Cette configuration s’applique uniformément aux worktrees créés avec --worktree, aux worktrees de subagents, et aux sessions parallèles de l’app desktop. Une seule configuration centralise tous les cas d’usage.
Plusieurs sessions Claude Code isolées dans des worktrees git séparés
Comment isoler les subagents avec des worktrees ?
Les subagents sont des agents secondaires que Claude délègue pour des tâches parallèles au sein d’une même conversation. Par défaut, ils travaillent dans le même répertoire que la session principale. Cela peut créer des conflits si deux subagents modifient les mêmes fichiers simultanément.
Pour activer l’isolation des subagents, demandez simplement à Claude d’utiliser des worktrees pour ses agents, ou configurez-le via le frontmatter d’un subagent custom avec isolation: worktree. Chaque subagent obtient alors son propre worktree temporaire pour travailler en toute sécurité.
Les worktrees de subagents sont automatiquement nettoyés à la fin de leur tâche si aucune modification n’a été effectuée. Si des changements existent, Claude vous demande si vous voulez les conserver ou les supprimer. Cette gestion automatique évite l’accumulation de worktrees orphelins.
Cette approche est particulièrement puissante pour les tâches de recherche ou d’analyse parallèle. Plusieurs subagents peuvent scanner différentes parties du codebase sans jamais interférer les uns avec les autres.
Voici les cas d’usage typiques pour l’isolation de subagents dans des worktrees :
- Recherche parallèle : plusieurs agents scannent différentes parties du codebase sans interférence
- Tests A/B de solutions : deux agents implémentent des approches différentes, vous comparez les résultats
- Refactoring progressif : un agent refactorise pendant qu’un autre maintient la compatibilité
- Code review assistée : un agent analyse le code pendant qu’un autre prépare les suggestions
- Migration de dépendances : un agent met à jour les deps pendant qu’un autre vérifie les breaking changes
Worktrees vs Subagents vs Agent Teams : quelle approche choisir ?
Claude Code propose trois méthodes distinctes pour le travail parallèle. Chacune répond à un besoin différent selon qui coordonne le travail et quel niveau d’autonomie vous souhaitez donner à l’IA.
Les worktrees sont idéaux quand vous pilotez vous-même plusieurs tâches indépendantes. Vous avez un terminal par worktree et vous basculez manuellement entre les sessions. C’est la méthode la plus contrôlée, recommandée quand vous voulez garder la main sur chaque session.
Les subagents conviennent aux tâches déléguées au sein d’une même session. Claude orchestre les agents et vous récupérez les résultats dans votre conversation principale. Moins de contrôle direct, plus d’automatisation du workflow.
Les agent teams poussent l’autonomie au maximum. Plusieurs sessions Claude communiquent entre elles via une liste de tâches partagée. C’est Claude qui gère le parallélisme complet, vous supervisez uniquement le résultat final. Idéal pour les projets complexes multi-composants.
Comment nettoyer et gérer vos worktrees proprement ?
Quand vous quittez une session worktree, le comportement de nettoyage dépend de l’état des fichiers. Si aucune modification n’existe, le worktree et sa branche sont supprimés automatiquement. C’est le comportement par défaut pour garder votre dépôt propre.
Si des commits ou des fichiers modifiés existent, Claude vous demande si vous voulez conserver ou supprimer le worktree. Conserver préserve le répertoire et la branche pour y revenir plus tard. Supprimer efface tout, y compris les commits non poussés.
Pour les worktrees manuels créés avec git directement, utilisez git worktree list pour voir tous vos worktrees actifs et git worktree remove <chemin> pour les supprimer. N’oubliez pas de supprimer aussi la branche associée avec git branch -d worktree-xxx si elle n’est plus utile.
Ajoutez .claude/worktrees/ à votre .gitignore global pour éviter que les fichiers des worktrees n’apparaissent comme non trackés dans votre checkout principal.
Nettoyage auto
Sans modification, le worktree est supprimé à la fin de session. Aucune action requise de votre part.
Conservation
Avec des commits, Claude propose de garder le worktree. Vous pouvez y revenir plus tard avec cd.
Suppression forcée
Utilisez git worktree remove pour supprimer manuellement. Attention aux commits non poussés.
Configuration avancée : baseRef et hooks custom
Par défaut, les worktrees branchent depuis origin/HEAD, donc la branche principale du remote. Cela garantit un départ propre aligné sur la production. Mais parfois, vous voulez partir de votre branche locale en cours avec vos commits non poussés.
Le setting worktree.baseRef accepte deux valeurs : fresh (défaut) pour partir du remote propre, ou head pour partir de votre HEAD local avec tout son historique. Configurez-le dans vos settings Claude Code pour changer le comportement global.
Pour un contrôle total sur la création des worktrees, les hooks WorktreeCreate et WorktreeRemove permettent de remplacer la logique git par défaut. C’est utile pour SVN, Perforce, Mercurial, ou d’autres systèmes de version non-git.
Le hook reçoit le nom du worktree en entrée JSON et doit retourner le chemin du répertoire créé sur stdout. Pensez aussi à ajouter .claude/worktrees/ à votre .gitignore pour garder un git status propre.
Erreurs courantes et solutions pratiques
L’erreur la plus fréquente est le workspace trust non accepté. Avant d’utiliser --worktree dans un répertoire pour la première fois, lancez claude sans arguments pour accepter la dialog de confiance workspace. Le flag -w échoue sinon avec un message explicite.
Si vos fichiers .env ne sont pas copiés dans le worktree, vérifiez qu’ils sont bien listés dans .worktreeinclude ET qu’ils sont gitignorés dans .gitignore. Les fichiers trackés ne sont jamais copiés par ce mécanisme pour éviter les duplications incohérentes.
Les worktrees orphelins après un crash ou une fermeture brutale du terminal sont nettoyés automatiquement au démarrage suivant, mais seulement s’ils sont plus vieux que cleanupPeriodDays et n’ont pas de modifications. Les worktrees que vous créez manuellement avec --worktree ne sont jamais supprimés par ce sweep automatique.
Enfin, attention aux dépendances du projet. Un nouveau worktree est un checkout frais : les node_modules, venv, vendor et autres dépendances installées ne sont pas présentes. Pensez à relancer votre script de setup ou npm install dans chaque nouveau worktree.
Questions fréquentes sur Claude Code Worktrees
Comment créer un worktree dans Claude Code ?
Pour créer un worktree, lancez Claude Code avec le flag --worktree ou -w suivi d’un nom descriptif. Par exemple, claude --worktree feature-auth crée un worktree nommé feature-auth avec sa propre branche git isolée. Le répertoire est créé automatiquement dans .claude/worktrees/ à la racine de votre projet.
Si vous omettez le nom, Claude génère un identifiant aléatoire comme bright-running-fox. Je recommande de toujours nommer vos worktrees explicitement pour les retrouver facilement plus tard. Vous pouvez aussi créer un worktree depuis une pull request existante en passant #1234 comme nom, ce qui fetch la branche correspondante du remote GitHub.
Quelle est la différence entre worktrees et subagents ?
Les worktrees sont des checkouts git isolés que vous pilotez manuellement dans des terminaux séparés. Chaque worktree est indépendant et vous basculez entre eux comme bon vous semble selon vos besoins. C’est vous qui coordonnez le travail entre les différentes sessions.
Les subagents sont des agents délégués par Claude au sein d’une même session principale. Claude orchestre automatiquement leur travail et vous récupérez les résultats dans votre conversation courante. Les subagents peuvent aussi utiliser des worktrees pour leur isolation, mais c’est Claude qui gère la création et le nettoyage automatiquement sans intervention manuelle.
Comment copier les fichiers .env dans un worktree ?
Créez un fichier .worktreeinclude à la racine de votre projet avec une ligne par fichier à copier. Ce fichier utilise la syntaxe gitignore pour lister les fichiers à copier automatiquement dans chaque nouveau worktree. Ajoutez vos fichiers : .env, .env.local, config/secrets.json, etc.
Important : seuls les fichiers qui matchent un pattern ET qui sont également gitignorés seront copiés dans le worktree. Les fichiers trackés par git ne sont jamais dupliqués pour éviter les incohérences. Cette configuration fonctionne pour tous les types de worktrees : manuels CLI, subagents, et sessions desktop.
Les worktrees fonctionnent-ils avec SVN ou Perforce ?
Par défaut, les worktrees Claude Code utilisent exclusivement git. Pour SVN, Perforce, Mercurial ou d’autres systèmes de version, vous devez configurer des hooks custom dans vos settings. Les hooks WorktreeCreate et WorktreeRemove remplacent entièrement la logique git par défaut.
Le hook WorktreeCreate reçoit le nom du worktree en entrée JSON et doit retourner le chemin du répertoire créé sur stdout. Vous pouvez y exécuter un svn checkout ou l’équivalent de votre VCS. Attention, le fichier .worktreeinclude n’est pas traité automatiquement avec les hooks custom.
Comment nettoyer les worktrees orphelins ?
Claude Code nettoie automatiquement les worktrees de subagents orphelins au démarrage de l’application, à condition qu’ils soient plus vieux que le setting cleanupPeriodDays et qu’ils n’aient pas de modifications non commitées ni de fichiers untracked. Ce sweep automatique ne touche jamais aux worktrees que vous créez manuellement avec --worktree.
Pour supprimer un worktree manuellement et définitivement, utilisez git worktree remove <chemin> dans votre terminal. Listez d’abord tous vos worktrees actifs avec git worktree list pour voir leur emplacement exact. N’oubliez pas de supprimer aussi la branche associée avec git branch -d worktree-xxx si elle n’est plus utile.
Peut-on partager un worktree entre plusieurs développeurs ?
Techniquement, un worktree est un répertoire local sur votre machine. Il ne peut pas être partagé directement entre développeurs comme une branche remote classique. Cependant, la branche créée dans le worktree peut être poussée sur le remote et récupérée par d’autres membres de l’équipe.
Pour collaborer efficacement sur un worktree, commitez vos changements locaux, poussez la branche avec git push -u origin worktree-feature, et vos collègues peuvent créer leur propre worktree sur cette branche partagée. Chacun conserve son checkout local indépendant mais partage les commits via le remote git.
Comment choisir la branche de base d’un worktree ?
Par défaut, tous les worktrees Claude Code branchent depuis origin/HEAD, la branche principale du remote. Pour partir plutôt de votre HEAD local avec vos commits non poussés, configurez worktree.baseRef à head dans vos settings Claude Code. Cela inclut tous vos commits locaux dans le nouveau worktree.
Pour une branche spécifique existante, créez le worktree manuellement avec la commande git native : git worktree add ../mon-worktree ma-branche-existante. Cette méthode vous donne un contrôle total sur l’emplacement du répertoire et la branche de base du worktree, hors du dossier .claude/.
Les worktrees ralentissent-ils Claude Code ?
Les worktrees n’ont aucun impact significatif sur les performances de Claude Code en utilisation normale. Ce sont des répertoires git standards, pas des conteneurs ou des machines virtuelles lourdes. La seule différence visible est que les fichiers sont stockés à un emplacement séparé du checkout principal.
Le temps de création initial est celui d’un git checkout classique, généralement quelques secondes seulement. Si votre projet contient beaucoup de fichiers volumineux ou de binaires, le premier worktree sera légèrement plus lent car git doit créer les copies physiques. Les worktrees suivants bénéficient du cache git et sont plus rapides.
Que se passe-t-il si je ferme le terminal sans quitter Claude ?
Si vous fermez brutalement le terminal ou si un crash survient, le worktree reste en place avec tous ses fichiers et commits intacts. Claude Code ne peut pas exécuter son prompt de nettoyage habituel dans ce cas. Le worktree devient alors orphelin jusqu’à votre prochaine session.
Au prochain démarrage de Claude Code, les worktrees de subagents orphelins sont nettoyés automatiquement selon vos settings cleanupPeriodDays. Les worktrees manuels créés avec --worktree ne sont jamais supprimés par ce sweep automatique. Utilisez git worktree list puis git worktree remove pour les nettoyer manuellement.
Puis-je utiliser les worktrees avec Claude Code Desktop ?
Oui, l’application desktop Claude Code crée automatiquement un worktree séparé pour chaque nouvelle session parallèle que vous ouvrez. C’est le comportement par défaut activé, vous n’avez rien à configurer manuellement. Chaque session dans l’interface possède son propre répertoire de travail complètement isolé.
Le fichier .worktreeinclude fonctionne exactement de la même manière avec les sessions desktop. Vos fichiers .env et secrets seront copiés automatiquement dans chaque nouvelle session ouverte. C’est la même logique que le flag -w en ligne de commande CLI, mais gérée graphiquement par l’application desktop.
