Worktrees Claude Code : des sessions parallèles sans conflits
Une commande donne à chaque session Claude Code sa copie complète de votre dépôt. Apprenez claude --worktree, l'organisation de .claude/worktrees, l'isolation en worktree des sous-agents, le nettoyage à la sortie — et là où le git worktree add manuel garde l'avantage.
L'essentiel
- claude --worktree (forme courte -w) démarre votre session dans une copie fraîche du dépôt sous .claude/worktrees/<name>, extraite sur une branche nommée worktree-<name>.
- Lancez d'autres sessions dans d'autres terminaux pour travailler en parallèle — chaque session modifie son propre répertoire tout en partageant le même historique Git et le même dépôt distant.
- Les sous-agents ont aussi leurs worktrees : demandez-le en langage naturel, ou posez isolation: worktree dans le frontmatter d'un .claude/agents/*.md pour le rendre permanent.
- À la sortie, les worktrees sans nom et propres sont retirés automatiquement et le travail en cours demande à conserver ou supprimer ; fusionnez les résultats avec un simple git merge de worktree-<name>.
Claude Code Worktrees in 7 Minutes
Chaîne : Developers Digest7:10
I'm using claude --worktree for everything now
Chaîne : Matt Pocock7:57
Worktrees — official documentation
Documentation officielle : code.claude.com/docs
Chaque option, chemin et comportement de nettoyage de cette page est vérifié contre la documentation officielle des worktrees ; les vidéos ci-dessus sont les sources visuelles et factuelles, y compris l'invite conserver/supprimer à la sortie et le piège du push vers main.
Les captures d'écran sont attribuées à leurs créateurs, avec des liens profonds vers les horodatages exacts. Aucune image de visage filmé n'est utilisée.
Utiliser les worktrees Claude Code, pas à pas
Partie 1 — Votre première session isolée
- 1
Préparer un dépôt Git avec au moins un commit
Les worktrees se ramifient depuis un historique existant ; la fonction worktree exige donc un vrai dépôt Git. Dans un dossier vierge, lancez git init, créez un fichier (la démo se contente de touch index.html) et commitez. Sans cela, Claude Code n'a rien depuis quoi se ramifier.
git init plus touch index.html — un seul commit suffit à la fonction worktree avant que claude --worktree ne fonctionne.Voir à 1:06 - 2
Savoir ce qu'est vraiment un worktree
Un worktree Git est un second répertoire de travail avec ses propres fichiers extraits et sa propre branche, qui partage l'historique et le dépôt distant. Contrairement à un changement de branche, rien n'est remisé : le checkout principal et chaque worktree restent utilisables en même temps — exactement ce dont les agents parallèles ont besoin.
Un dépôt, plusieurs dossiers de travail : ../main, ../feature1 et ../feature2 se trouvent en même temps sur leur propre branche.Voir à 0:30 - 3
Lancer Claude Code avec --worktree
Depuis l'intérieur du dépôt, lancez claude --worktree (ou la forme courte claude -w). Claude Code crée .claude/worktrees/<name>, génère un nom comme bright-tumbling-rabbit si vous n'en passez pas et installe la session directement dans cette copie. Dans l'application de bureau, vous choisissez l'option worktree au démarrage de la session.
Le bandeau de bienvenue montre que le répertoire de travail de la session est déjà sous .claude/worktrees — tout ce qui suit se passe dans la copie.Voir à 1:22 - 4
Ouvrir une seconde session pour votre seconde tâche
Relancez claude --worktree dans un autre terminal. Sans nom, vous obtenez un autre worktree indépendant ; passez deux fois le même nom pour rouvrir le même. Deux agents peuvent désormais modifier le même projet simultanément, car chacun ne voit que son propre répertoire.
Partie 2 — Où vivent vos fichiers et commandes
- 5
Inspecter la copie complète sous .claude/worktrees
Ouvrez le dossier dans votre gestionnaire de fichiers : chaque worktree est un checkout complet avec son propre index.html, son propre .claude/settings.local.json et son propre fichier git, tandis que la lourde base d'objets reste partagée dans le .git principal. C'est pourquoi une copie supplémentaire ne coûte presque rien.
Deux worktrees sur le disque — clever-munching-toast et spicy-napping-otter — chacun une copie complète du projet avec son dossier git et son index.html.Voir à 1:50 - 6
Vérifier que les commandes restent dans le worktree
Quand la première session ouvre sa page dans le navigateur, la demande de permission montre que le chemin pointe vers .claude/worktrees/clever-munching-toast — pas vers votre checkout principal. Claude Code empêche aussi les sous-agents de modifier directement le checkout principal, et l'une de ces vérifications d'isolation ne peut pas être désactivée.
La boîte de dialogue d'approbation nomme le chemin exact du worktree, la preuve que la session un ne touche jamais que sa propre copie du projet.Voir à 1:42 - 7
Nommer les worktrees ou se ramifier depuis une PR (optionnel)
claude --worktree feature-auth crée un worktree nommé prévisible, et relancer le même nom le rouvre au lieu de créer un doublon. Vous pouvez aussi passer un numéro de PR entre guillemets (claude --worktree "#1234") ou une URL de PR GitHub/GitLab pour obtenir le worktree de cette pull request sous .claude/worktrees/pr-<number>.
Partie 3 — Sous-agents en parallèle et nettoyage
- 8
Demander des sous-agents parallèles avec isolation en worktree
L'isolation s'étend au-delà des terminaux. Un seul prompt — « lance cinq sous-agents différents pour créer cinq variantes en tirant parti de l'isolation git worktree » — fait naître des agents Task chez Claude Code, chacun dans son propre worktree isolé, tous sur le même dépôt en même temps sans collisions.
Cinq agents Task lancés en parallèle, chacun annoncé comme travaillant dans son propre git worktree isolé.Voir à 2:42 - 9
Regarder chaque agent courir dans son propre couloir
La liste des tâches montre les cinq variantes avec leurs usages d'outils et leurs comptes de tokens, vous suivez la progression sans ouvrir cinq terminaux. Les transcriptions des sous-agents restent hors du contexte du fil principal, ce qui garde la session d'orchestration légère pendant que les agents font le gros du travail.
Les cinq sous-agents en pleine exécution — la Variante 1 déjà terminée à 50,3k tokens pendant que les autres lisent des fichiers dans leurs worktrees.Voir à 3:42 - 10
Comparer les variantes, puis fusionner la gagnante
Quand les agents ont fini, Claude Code liste chaque variante avec son chemin sous .claude/worktrees/agent-<id>/, de quoi les ouvrir côte à côte dans le navigateur. Livrez celle que vous préférez par un simple git merge de sa branche de worktree (ou via une PR) — les conflits, s'il y en a, se résolvent comme n'importe quel merge Git.
Le récapitulatif nomme chaque variante et son chemin .claude/worktrees, avec un résultat rendu ouvert à côté de la liste.Voir à 4:22 - 11
Graver l'isolation dans un sous-agent réutilisable
Pour rendre l'isolation en worktree permanente, demandez simplement : « crée un sous-agent développeur front-end, utilise le modèle Haiku et fais qu'il tire parti de l'isolation en worktree. » Claude Code consulte sa propre documentation d'agents et vous écrit un nouveau fichier sous .claude/agents/.
Le langage naturel suffit — Claude Code vérifie sa propre documentation sur le format des agents personnalisés avant d'écrire le fichier.Voir à 5:42 - 12
Vérifier le isolation: worktree du frontmatter
Le frontend-dev.md généré porte name, description, model: haiku, une liste blanche d'outils et — la ligne nouvelle — isolation: worktree. Chaque exécution future de ce sous-agent se déroule désormais dans un worktree temporaire, retiré automatiquement s'il se termine sans modifications.
La ligne 8 du frontmatter — isolation: worktree — donne à chaque exécution de ce sous-agent son propre worktree.Voir à 6:42 - 13
Fusionner, puis laisser Claude nettoyer
Quand vous quittez une session, Claude Code inspecte le worktree : les worktrees sans nom et propres sont retirés automatiquement, tout ce qui contient du travail demande à conserver ou supprimer — conserver affiche la commande claude --worktree <name> --resume pour plus tard. Les exécutions headless avec -p ne nettoient jamais ; supprimez-les avec git worktree remove.
Worktrees Claude Code vs git worktree add manuel
Les worktrees font partie de Git depuis des années — la nouveauté, c'est que Claude Code gère tout leur cycle de vie. Les différences qui comptent :
- 1Création : à la main, vous lancez git worktree add ../project-feature -b feature, vous vous y déplacez, puis démarrez Claude. Avec claude --worktree, la session atterrit sous .claude/worktrees/<name> en une étape, nommé par vous ou pour vous.
- 2Commit de base : worktree.baseRef contrôle le point de départ — fresh (défaut) se ramifie depuis la branche par défaut du dépôt distant, head emporte vos commits locaux non poussés. L'option ne peut pas viser une branche précise ; la documentation renvoie au git worktree add manuel pour cela.
- 3Dotfiles : un fichier .worktreeinclude à la racine du projet copie les fichiers gitignorés comme .env dans chaque nouveau worktree. Les worktrees faits main n'ont pas droit à ce traitement.
- 4Nettoyage : Claude Code inspecte un worktree à la sortie, retire automatiquement les sans-nom propres, demande avant de toucher au travail en cours et balaye périodiquement les worktrees de sous-agents abandonnés. Les worktrees manuels sont entièrement de votre responsabilité.
- 5Garde-fous : des vérifications d'isolation empêchent les sous-agents de modifier le checkout principal, et reprendre une session vous ramène dans son worktree. Le simple git worktree add n'a pas d'équivalent.
En dessous, c'est toujours du Git ordinaire. Le panneau contrôle de source de VS Code liste chaque worktree avec ses changements, les merges sont des git merges ordinaires, et worktrees faits main et créés par Claude cohabitent dans le même dépôt — choisissez l'outil selon la tâche.
Quand un worktree ne se comporte pas
La plupart des pièges sont des fondamentaux de Git qui transparaissent, pas des bugs de la fonction. Ces cinq-là couvrent presque tous les angles rugueux :
- 1Le push atterrit sur main. Une branche de worktree fraîche suit la branche par défaut d'origin, un git push nu peut donc viser main. Poussez explicitement avec git push origin worktree-<name> et gardez main protégée.
- 2Fichiers ou outils manquants. Les fichiers gitignorés (.env, dossiers vendor) et les pilotes de filtre propres au dépôt comme LFS ne se propagent pas dans un nouveau worktree. Listez-les dans .worktreeinclude, ou lancez git lfs pull et vos commandes de configuration dans le worktree.
- 3Le lancement échoue avec une erreur de confiance. Dans un répertoire non approuvé, claude --worktree se termine avec une erreur vous invitant d'abord à accepter l'espace de travail — approuvez et relancez. (Les exécutions non interactives avec -p sautent la vérification.)
- 4Deux worktrees se percutent au moment du merge. Si les deux tâches modifient le même fichier — routes, barre latérale, package.json — vous résoudrez des conflits en fusionnant, comme dans tout flux Git. Les worktrees suppriment les collisions en cours d'exécution, pas les intentions qui se chevauchent.
- 5Des worktrees orphelins après des exécutions headless. Les exécutions -p ne nettoient jamais derrière elles ; supprimez-les à la main avec git worktree remove (lancez d'abord git worktree unlock si l'un est verrouillé).
Supprimer un worktree sous les pieds d'une session n'est pas fatal non plus : la reprise suivante retombe sur le répertoire de lancement et le lien est effacé. Rien d'autre ne casse dans la session.