Exécuter les sessions Claude Code l'une après l'autre est une habitude, pas une obligation. Quand vos tâches sont vraiment indépendantes, il n'y a aucune raison qu'une doive attendre l'autre. Les worktrees Git donnent à chaque session Claude son propre répertoire extrait sur sa propre branche, tous puisant dans le même magasin d'objets .git. Pas de clones en doublon, pas de conflits de fichiers, fusion git standard quand vous avez terminé. Cet article vous guide à travers l'intégralité du flux de travail : quand utiliser un worktree, comment en configurer un, quel isolement vous obtenez réellement (et ce que vous ne faites pas), et comment nettoyer sans perdre le travail qui n'a pas encore été validé.
Quand un Worktree est utile
Pas chaque tâche n'en justifie un. Réponse honnête : les worktrees brillent dans une bande assez spécifique de situations.
Une démonstration YouTube par bri (juin 2026) l'explique bien. Utilisez un worktree quand vous avez deux tâches ou plus qui ne partagent pas les mêmes fichiers, ou quand une tâche est assez risquée pour que vous vouliez voir deux approches différentes avant de vous engager sur l'une ou l'autre. Si une seule tâche couvre l'ensemble de la base de code, en tenez-vous à une session. Même chose pour le travail exploratoire où vous voulez que l'agent se déplace librement.
L'autre cas d'usage intéressant : le travail spéculatif. Lancez trois worktrees, donnez à chacun une invite légèrement différente pour le même problème, et choisissez la version que vous aimez. Zylos Research note que ce motif est devenu courant dans les équipes exécutant quatre sessions IA ou plus en parallèle, précisément parce que vous vous couvrez contre la sortie non déterministe du modèle plutôt que de vous fier à une seule tentative.
À l'inverse, si votre projet implique un grand monorepo TypeScript avec PostgreSQL, Redis, plusieurs packages internes et un frontend Remix, les worktrees seuls ne résoudront pas vos problèmes de coordination. Trigger.dev a écrit précisément sur ce sujet et a finalement adopté une approche différente. L'isolement du système de fichiers est réel. L'isolement des services n'est pas automatique.
Créer des extractions de tâches isolées
Commencez sur votre branche de base et tirez les dernières mises à jour. Ensuite, ajoutez .claude/worktrees à votre .gitignore une seule fois :
echo ".claude/worktrees" >> .gitignore
Claude place les worktrees à l'intérieur de votre répertoire de dépôt par défaut. Sans cette entrée .gitignore, ils apparaissent comme des fichiers non suivis et encombrent votre git status. Ajoutez-la, validez-la, oubliez-la.
Maintenant lancez une session par tâche. Ouvrez deux terminaux :
claude --worktree feature-payments
``
claude --worktree bugfix-auth
Selon la description de Dan Does Code, Claude crée le worktree à .claude/worktrees/feature-payments/, extrait une nouvelle branche et limite la session à ce répertoire. Votre arborescence de travail principale reste intacte tout au long du processus. Vous pouvez aussi utiliser la forme de flag abrégée claude -w feature-payments si vous préférez. Omettez complètement le nom et Claude en génère un automatiquement.
Chaque session opère maintenant en isolement complet du système de fichiers. L'agent du Terminal 1 ne peut pas toucher aux fichiers sur lesquels l'agent du Terminal 2 travaille, parce qu'ils se trouvent dans des répertoires différents sur des branches différentes. C'est toute la ruse. C'est une séparation au niveau de l'infrastructure, pas une logique de coordination entre les agents. (Le guide des subagents Claude Code couvre le côté orchestration si c'est plutôt cela que vous cherchez.)
Donner à chaque session sa tâche
Une fois les deux sessions en cours d'exécution, donnez à chacune ses instructions. Traitez chaque instance Claude comme un contexte vierge. Soyez précis sur la portée. Si Terminal 1 crée une fonctionnalité de paiement, dites-lui quels fichiers toucher et lesquels laisser de côté. Idem pour Terminal 2.
Quand une session se termine, demandez à Claude de pousser la branche et d'ouvrir une pull request avant de fermer le terminal. De cette façon, le travail est en sécurité en dehors de votre machine locale et prêt à être examiné.
Gérer les dépendances, les ports et la configuration locale
C'est là que les choses deviennent délicates. L'isolation du système de fichiers est automatique. Tout le reste nécessite un peu de configuration manuelle.
Ports. Si les deux worktrees lancent un serveur de développement, ils entreront en collision sur le même port par défaut. La solution est de donner à chaque worktree son propre fichier .env avec une attribution de port différente. Par exemple PORT=3001 dans l'un et PORT=3002 dans l'autre. Ou passez le remplacement en ligne au démarrage. L'une ou l'autre solution fonctionne.
Bases de données. SQLite est facile : pointez le .env de chaque worktree vers un chemin de fichier différent. PostgreSQL ou MySQL nécessite plus de réflexion. Vous avez besoin soit d'une instance de base de données séparée par worktree, soit au minimum d'un schéma/base de données distinct au sein de la même instance. Configurez la chaîne de connexion via des variables d'environnement dans le .env de chaque worktree. Ne partagez pas une base de données entre deux agents écrivant des migrations simultanément. C'est demander une corruption ou des conditions de concurrence.
Fichiers de configuration locale. Si votre projet utilise un fichier de configuration locale qui n'est pas committé (comme .env.local, config/local.yml), vous devrez en créer un par worktree. Ils n'héritent pas automatiquement de l'arborescence de travail principale.
Le guide de MindStudio sur les agents de codage IA parallèles couvre ces modèles d'isolation plus en détail. En résumé : les worktrees vous donnent l'isolation de branche et de répertoire par conception. L'isolation de base de données et de port nécessite que vous la configuriez explicitement, en amont.
Une autre chose mérite d'être signalée. Si vous travaillez sur un projet avec une configuration de service locale coûteuse ou compliquée et que vous exécutez plusieurs worktrees, considérez si le coût de la configuration vaut l'accélération parallèle. Pour une bibliothèque ou un outil CLI, absolument. Pour une monorepo full-stack avec six services, peut-être moins. Si vous voulez de l'aide pour délimiter cela, un développeur Claude Code peut évaluer si les worktrees ou une stratégie parallèle différente conviennent à votre pile.
Examiner et intégrer les deux branches
Les deux agents ont terminé. Les deux branches sont poussées. Maintenant, vous examinez.
Le workflow ici est le git standard. La configuration parallèle ne change pas du tout le processus de fusion. Une séquence numérotée pour un dépôt typique à deux tâches :
- Allez à
mainet tirez la dernière version. - Examinez la première branche.
git diff main..feature-paymentsvous donne une image complète de ce qui a changé. - Si vous en êtes satisfait, fusionnez ou rebasez dans
main. Résolvez les conflits avec la branche de base de la manière habituelle. - Tirez à nouveau
mainpour obtenir ces modifications. - Examinez la deuxième branche.
git diff main..bugfix-auth. - Fusionnez. Si les deux agents ont modifié des fichiers qui se chevauchent (ce qui ne devrait pas arriver si vous avez correctement délimité les tâches, mais cela arrive parfois), résolvez les conflits ici.
- Exécutez votre suite de tests sur
mainune fois que les deux fusions sont en place.
L'avantage d'examiner séquentiellement comme cela, plutôt que de fusionner les deux simultanément, est que les conflits d'une fusion ne se composent pas dans la suivante. Des diffs plus simples, un raisonnement plus facile.
Nettoyer sans perdre le travail non commité
Le nettoyage est là où les développeurs deviennent nerveux. Et s'il y avait du travail dans un worktree qui n'a jamais été commité ?
La réponse : rangez-le avant de supprimer le worktree.
Si vous avez des modifications non validées dans une arborescence de travail que vous voulez conserver, accédez à ce répertoire et exécutez :
git stash push -m "wip: payments feature - pre-cleanup"
Ce stash réside dans le magasin d'objets .git partagé, ce qui signifie qu'il est accessible depuis votre arborescence de travail principale ou toute autre arborescence après la suppression de l'arborescence d'origine. Une fois le stash créé, vous pouvez supprimer en toute sécurité :
git worktree remove .claude/worktrees/feature-payments
Ensuite, de retour dans votre arborescence de travail principale, récupérez le stash :
git stash pop
Si l'expérience a échoué complètement et que vous ne voulez rien en garder, supprimez simplement sans stasher. git worktree remove avec le flag --force supprime l'arborescence même si elle a des modifications non validées. Soyez certain avant d'utiliser --force. Il n'y a pas de chemin de récupération.
Après avoir supprimé tous les worktrees, nettoyez la liste :
git worktree prune
Cela supprime toute référence administrative obsolète de .git/worktrees/.
Ressources Partagées Que Les Worktrees N'Isolent Pas
Il vaut mieux être explicite à ce sujet, car le modèle mental « d'isolation » peut vous induire en erreur.
Ce que les worktrees isolent :
- Le répertoire de travail et tous les fichiers qu'il contient
- La branche sur laquelle chaque session opère
- Les modifications en attente et non en attente
Ce que les worktrees n'isolent pas :
- Le magasin d'objets
.git(partagé par conception) - La mémoire auto de la machine (la documentation officielle de mémoire confirme que les worktrees du même référentiel partagent cela)
- Services externes : bases de données, files d'attente, caches, toute dépendance en réseau
- Identifiants d'environnement et clés API sauf si vous définissez explicitement des valeurs différentes par worktree
- Tout ce qui se trouve dans l'environnement shell au niveau du système d'exploitation que les deux sessions héritent
Cela compte aussi pour la sécurité. Les worktrees ne sont pas une limite de tenant. Si les deux sessions partagent la même clé API ou les mêmes identifiants de base de données, elles partagent l'accès. Ne traitez pas un worktree comme un moyen de mettre en sandbox une session Claude par rapport à une config locale sensible. Ce n'est pas le cas.
Pour orchestrer plusieurs agents sur un flux de travail plus large plutôt que juste l'isolation du système de fichiers, le post des superpuissances Claude Code aborde les schémas plus larges.
FAQ
Est-ce que `claude --worktree` fonctionne de la même façon que d'exécuter `git worktree add` manuellement ?
Fonctionnellement similaire mais pas identique. claude --worktree fait le git worktree add , crée la branche et limite la session Claude à ce répertoire en une seule étape. Si vous exécutez git worktree add manuellement puis démarrez Claude dans le répertoire résultant, vous obtenez le même résultat de système de fichiers mais sans la limitation intégrée de Claude. Le flag --worktree est le chemin plus rapide pour le cas courant.
Puis-je exécuter plus de deux worktrees à la fois ?
Oui. Il n'y a pas de limite stricte imposée par git ou Claude Code sur le nombre de worktrees. La limite pratique est la RAM et le CPU de votre machine. Chaque session Claude est un processus distinct avec son propre contexte. Trois ou quatre sessions simultanées sur une machine de développement moderne fonctionnent bien. Au-delà et vous êtes probablement en train de frapper des contraintes de ressources avant d'atteindre une limitation git.
Qu'advient-il de la branche d'un worktree si je le supprime ?
La branche persiste. git worktree remove supprime le répertoire de travail et la référence administrative dans .git/worktrees/. La branche elle-même reste et est accessible depuis votre arborescence de travail principale ou n'importe quel autre worktree. Vous supprimez la branche séparément avec git branch -d branch-name quand vous n'en avez plus besoin.
Les worktrees affectent-ils la façon dont Claude lit ou écrit le fichier `CLAUDE.md` de mémoire de projet ?
Les worktrees d'un même dépôt partagent la mémoire auto locale à la machine selon la documentation officielle de la mémoire. Si vous avez un fichier CLAUDE.md commité dans le dépôt, chaque worktree le lit depuis sa propre copie extraite. Les modifications qu'un agent apporte à CLAUDE.md dans son worktree restent isolées sur cette branche jusqu'à la fusion. Mais la couche locale à la machine est partagée, donc les instructions écrites là par une session sont visibles à une autre.
Y a-t-il un coût de performance à utiliser des worktrees par rapport à des clones séparés ?
Les worktrees sont moins coûteux que les clones. Ils partagent le magasin d'objets .git, il n'y a donc pas de duplication de tout l'historique du dépôt sur disque. Le coût principal est le répertoire de travail lui-même, qui est une extraction complète de tous les fichiers suivis à l'état actuel de la branche. Pour les gros dépôts avec des actifs binaires ou des fichiers générés, la taille de cette extraction peut s'accumuler. Mais les opérations git (fetch, log, diff) s'exécutent toutes sur un magasin d'objets unique, elles sont donc rapides.
La raison la plus nette de préférer les worktrees aux clones séparés : les stashes et les références créés dans un worktree sont immédiatement accessibles partout ailleurs dans le même dépôt. Cet état partagé est exactement ce qui rend le flux de nettoyage ci-dessus fonctionnel.