Les Worktrees avec Claude Code

Le problème : Une session Claude Code tourne sur une branche de fonctionnalité, et un bug de production atterrit sur ton bureau. Tes options sont mauvaises : stash et perd l'état de travail, ouvre un second terminal et regarde les deux sessions se battre sur les mêmes fichiers, ou abandonne la session complètement.

Solution rapide : Ouvre une seconde session Claude Code dans son propre worktree :

claude --worktree bugfix-123

Un nouveau répertoire de travail apparaît dans .claude/worktrees/bugfix-123/ sur sa propre branche, worktree-bugfix-123. La première session est laissée intacte. Rien n'est stashe. Rien ne rentre en collision. Deux sessions Claude tournent côte à côte, et aucune ne sait que l'autre existe.

Si tu dois choisir entre des patterns d'agents, garde la limite simple : lis Agent Fundamentals quand tu as besoin de sous-agents, de slash commands, ou de spécialisation légère dans une seule session. Lis cette page quand le vrai problème c'est l'isolation du système de fichiers, des branches séparées, et du travail parallèle qui ne doit pas toucher le même checkout. Pour les formes d'orchestration par-dessus cette isolation, lis Agent Patterns.

Pourquoi les worktrees changent tout

Quiconque a poussé Claude Code avec des sous-agents ou des agents en arrière-plan a atteint le plafond. Deux agents commencent à modifier le même fichier en même temps. L'un réécrit src/auth.ts pendant que l'autre est à mi-chemin dans le même module. Ce qui revient c'est des modifications à moitié appliquées, un beau bazar de fusion, ou quelque chose de pire.

Les worktrees règlent ça au niveau du système de fichiers. Chacun est un checkout séparé du repo avec sa propre branche, son propre répertoire, et son propre index. Le support des worktrees est devenu de premier ordre dans Claude Code v2.1.50, ce qui couvre leur création, leur gestion, et leur nettoyage depuis le CLI, l'app Desktop, et même les agents personnalisés.

Le CLI : le flag --worktree

Lancer Claude Code avec le flag --worktree c'est le chemin le plus rapide.

Worktrees nommés

# Démarrer Claude dans un worktree nommé
claude --worktree feature-auth
 
# Crée :
# .claude/worktrees/feature-auth/  (répertoire de travail)
# Branche : worktree-feature-auth    (basée sur la branche distante par défaut)

Chaque worktree se pose dans son propre dossier sous .claude/worktrees/ sur une branche dédiée. Lance-en autant que ton disque peut en supporter.

Worktrees nommés automatiquement

# Laisser Claude générer un nom
claude --worktree

Pratique pour les runs jetables où le nom de la branche n'a vraiment pas d'importance.

Sessions parallèles multiples

# Terminal 1 : travail sur l'auth
claude --worktree feature-auth
 
# Terminal 2 : correction d'un bug
claude --worktree bugfix-123
 
# Terminal 3 : exploration d'un refactor
claude --worktree experiment-new-router

Trois sessions. Trois branches. Zéro conflit. Chacune peut lire tout l'historique git, mais les fichiers de chaque session vivent dans leur propre arbre.

Création de worktree en cours de session

Le flag n'est pas requis au lancement. Tu peux demander dans n'importe quelle session active :

Toi : work in a worktree
Claude : I'll create an isolated worktree for this session...

Claude configure le worktree et déplace la session dedans. Ça te sauve quand tu réalises, à mi-conversation, que le travail aurait dû être isolé dès le départ.

App Desktop : isolation automatique

L'app Desktop Claude Code va encore plus loin. Chaque nouvelle session obtient son propre worktree par défaut.

Par défaut, ces worktrees se posent dans .claude/worktrees/. Les paramètres Desktop te laissent changer le chemin et définir un préfixe de branche pour que les branches créées par Claude restent regroupées. Tu en as fini avec une session ? Appuie sur l'icône d'archivage et le worktree ainsi que sa branche disparaissent.

Donc chaque session Desktop est sûre dès la sortie de la boîte. Les sessions ne s'écrasent pas mutuellement, et tu n'as pas à les coordonner.

Isolation des worktrees pour les sous-agents

C'est là que la fonctionnalité paie. Chaque sous-agent que Claude lance pour une tâche distribuée peut avoir son propre worktree.

Demander à Claude d'isoler les agents

Version la plus simple :

Toi : Use worktrees for your agents when doing this refactor

Chaque sous-agent se pose dans son propre worktree. Un worktree qui se termine sans modifications est supprimé tout seul. Un worktree qui a effectivement changé quelque chose reste pour que tu puisses le lire.

Pourquoi c'est important pour l'exécution parallèle

Sans isolation, les sous-agents parallèles peuvent seulement lire des fichiers ou écrire dans des chemins non-overlapping. C'est une limite faible. Dès qu'un agent empiète sur le territoire d'un autre, tu obtiens des conflits silencieux.

Avec l'isolation, chaque agent voit tout le codebase par lui-même. L'agent A peut tenter src/auth.ts d'une façon pendant que l'agent B tente le même fichier d'une autre façon. Tu ouvres les deux branches ensuite et tu choisis la meilleure (ou tu assembles des morceaux des deux).

C'est vraiment utile pour les migrations par lots. Tu as 50 fichiers à migrer d'une API à une autre ? Lance cinq agents, dix fichiers chacun, chacun dans son propre worktree. Ils travaillent en parallèle et personne ne se marche dessus. La commande intégrée /batch utilise ce même rail, lançant des agents isolés par worktree depuis un seul prompt pour effectuer des migrations à travers un codebase.

Agents personnalisés avec isolation intégrée

Les agents personnalisés sous .claude/agents/ peuvent être configurés pour toujours utiliser un worktree :

---
name: refactor-agent
description: Agent that performs isolated refactoring work
isolation: worktree
---
You are a refactoring specialist. Analyze the target code,
plan the refactor, and implement changes.

isolation: worktree dans le frontmatter dit à Claude de créer un nouveau worktree à chaque fois que cet agent tourne. L'agent travaille en isolation complète, et un worktree vide se supprime lui-même à la fin du run.

Support VCS non-Git

Les équipes sur Mercurial, Perforce, ou SVN ne sont pas exclues. Le mode worktree tourne quand même, en utilisant des hooks personnalisés. Enregistre des hooks WorktreeCreate et WorktreeRemove dans tes paramètres pour que la logique d'isolation de ton propre VCS remplace le comportement git par défaut.

Avec ces hooks en place, le flag --worktree et les demandes de worktrees en cours de session passent par tes hooks plutôt que d'appeler git en shell. Tout le reste du flux reste inchangé.

Trois patterns de worktree à voler

La plupart des équipes comprennent l'idée de base une fois qu'elles la voient. Ce dont elles ont généralement besoin ensuite, c'est un pattern fonctionnel qu'elles peuvent copier.

1. Hotfix sans exploser le travail en cours

Tu es à mi-chemin d'une branche de fonctionnalité quand un bug d'auth de production arrive.

# Garde ta session de fonctionnalité actuelle active
claude

# Ouvre une seconde session de bugfix isolée
claude --worktree hotfix-auth-timeout

Maintenant le hotfix peut être livré proprement pendant que la session de fonctionnalité conserve son état, ses todos, et son historique de conversation. C'est l'utilisation la plus simple et la plus utile des worktrees, et celle que la plupart des équipes adoptent en premier.

2. Implémentations concurrentes pour le même refactor risqué

Supposons qu'un refactor de routing ait deux formes possibles. L'une conserve la surface API actuelle et déplace les internals. L'autre simplifie aussi l'API externe.

Lance les deux :

claude --worktree router-safe-path
claude --worktree router-clean-slate

Les deux sessions peuvent toucher les mêmes fichiers car elles ne partagent pas un checkout. Revois les deux branches après coup et garde le meilleur design. C'est bien mieux que d'essayer de forcer un seul agent à raisonner sur les deux chemins dans un seul contexte.

3. Migrations par lots avec des sous-agents isolés

Disons que tu dois remplacer une API de logging dans 80 fichiers. Tu ne veux pas cinq agents qui modifient le même checkout.

Demande la division explicitement :

Toi : Use worktrees for agents. Split this migration into 5 batches of files.

Ça donne à chaque worker :

• une vue complète du repo
• un lot de fichiers limité
• une branche isolée
• un résultat vérifiable

C'est là que les worktrees cessent d'être une fonctionnalité de confort et commencent à se comporter comme une véritable infrastructure parallèle.

Petites règles pour garder les worktrees sains

La mécanique est simple. Ce sont les habitudes d'équipe qui les maintiennent utiles :

• Nomme les worktrees d'après le résultat, pas juste le ticket
• Supprime rapidement les worktrees vides ou abandonnés
• Utilise un worktree par ligne de pensée active
• Garde des préfixes de branche cohérents pour que le nettoyage soit évident
• Revois les diffs avant de fusionner entre worktrees comme pour n'importe quelle autre branche

Si les worktrees commencent à sembler désordonnés, c'est généralement pas parce qu'il y en a trop. C'est parce que personne ne sait lesquels sont jetables et lesquels comptent.

Nettoyage et entretien

Comment un worktree est nettoyé dépend de s'il y a eu des modifications dedans :

• Pas de modifications : Le worktree et sa branche sont automatiquement supprimés à la fin de la session
• Des modifications existent : Claude te demande si tu veux garder ou supprimer le worktree

Garde les dossiers de worktrees hors du contrôle de version avec une ligne dans .gitignore :

echo ".claude/worktrees/" >> .gitignore

Les worktrees s'accumulent ? Les commandes git classiques les listent et les nettoient :

git worktree list
git worktree prune

Quand utiliser les worktrees

Règle générale : chaque fois que tu te tournerais vers une branche séparée pour éviter les conflits, tourne-toi vers un worktree à la place. Tu obtiens la branche, et tu obtiens un répertoire de travail séparé avec.

Retiens ça : Les worktrees transforment Claude Code d'un thread unique en un environnement de développement parallèle. Lance des sessions isolées. Dispatche des agents isolés. Fusionne les gagnants quand tu es prêt.