Guide complet de Claude Worktree

Introduction

Lorsque vous travaillez sur des tâches complexes avec Claude Code, vous avez peut-être rencontré ce dilemme : vous avez trois tâches indépendantes à traiter, mais exécuter plusieurs instances de Claude dans le même répertoire provoque des conflits de code — un Agent modifie des fichiers pendant qu'un autre touche aux mêmes, et le résultat lors de la fusion est un vrai désordre.

En février 2025, Anthropic a publié la commande --worktree, changeant complètement la donne. Désormais, vous pouvez exécuter claude -w feature-1, claude -w feature-2 et claude -w bugfix-1 dans trois terminaux distincts, chaque Agent travaillant dans son propre environnement isolé sans interférer avec les autres.

Comprendre Worktree

Imaginez que vous êtes un architecte concevant trois pièces différentes simultanément. L'approche traditionnelle consiste à dessiner sur le même plan, ce qui devient confus avec les modifications constantes. Worktree vous donne trois plans distincts, chacun dédié à la conception d'une pièce, pour être ensuite fusionnés dans le plan principal.

Techniquement, Worktree est une fonctionnalité native de Git. La commande --worktree de Claude Code encapsule cette fonctionnalité pour la rendre beaucoup plus simple — une seule commande crée un environnement isolé, lance une instance de Claude et nettoie automatiquement une fois terminé.

Pourquoi ne pas simplement cloner plusieurs fois

Vous pourriez demander : pourquoi ne pas simplement cloner le dépôt plusieurs fois ?

Les worktrees partagent la même base de données .git — tout l'historique des commits et les informations de branches sont partagés. Cela signifie qu'un commit créé dans un worktree est immédiatement visible dans tous les autres.

Quand utiliser Worktree

Avant de vous lancer, évaluez si votre tâche se prête bien à l'utilisation d'un worktree.

Règle générale : si une tâche nécessite plus de 30 minutes, envisagez d'utiliser un worktree. Pour les tâches courtes, le worktree est un gaspillage de temps — créer l'environnement, installer les dépendances, puis fusionner peut prendre plus longtemps que la tâche elle-même. Mais pour les tâches nécessitant un travail approfondi, l'isolation du worktree devient très précieuse.

Prérequis

Avant d'utiliser worktree, assurez-vous que les conditions suivantes sont remplies :

Flux de travail complet : de la création au nettoyage

Voici le flux de travail complet, de la création d'un Worktree jusqu'au nettoyage final, dans l'ordre réel de développement.

Étape 1 : Créer un Worktree

Création depuis la branche distante par défaut

Utilisez le paramètre -w ou --worktree pour lancer Claude :

# Créer un worktree nommé "feature-auth" et lancer Claude
claude -w feature-auth

# Générer automatiquement un nom aléatoire (ex. "bright-running-fox")
claude -w

Cette commande effectue en réalité quatre opérations :

1. Crée un nouveau répertoire de travail dans <repo>/.claude/worktrees/feature-auth/
2. Crée une nouvelle branche nommée worktree-feature-auth
3. Extrait le code depuis la branche distante par défaut (ex. origin/main ou origin/master) — attention, ce n'est pas votre branche actuelle
4. Lance Claude Code dans le nouveau répertoire

Tous les worktrees se trouvent dans le répertoire .claude/worktrees/ :

votre-projet/
├── .claude/
│   └── worktrees/
│       ├── feature-auth/      ← Premier worktree
│       ├── bugfix-123/        ← Deuxième worktree
│       └── refactor-api/      ← Troisième worktree
├── src/
└── package.json

Il est recommandé d'ajouter ce chemin au .gitignore :

# .gitignore
.claude/worktrees/

Création depuis la branche actuelle/spécifique

-w extrait toujours depuis la branche distante par défaut et ne permet pas actuellement de spécifier une branche de base. Si vous souhaitez créer un worktree basé sur votre branche actuelle (ou une branche spécifique), trois approches sont possibles :

Approche 1 : Création manuelle avec Git

# Créer un worktree basé sur le HEAD actuel
git worktree add -b my-feature .claude/worktrees/my-feature HEAD

# Ou basé sur une branche spécifique
git worktree add -b hotfix .claude/worktrees/hotfix origin/release-v2

# Puis lancer Claude dans ce répertoire
cd .claude/worktrees/my-feature && claude

Cette approche vous donne un contrôle total — vous pouvez créer des worktrees à partir de n'importe quelle branche ou commit, et le répertoire de travail démarre sur la bonne branche dès le début. La documentation officielle recommande également : « Pour un contrôle accru sur la branche et l'emplacement, créez le worktree directement avec Git, puis exécutez Claude dans ce répertoire. »

Approche 2 : Création dans une session (recommandée)

Dans une session Claude existante, demandez simplement à Claude de créer un worktree :

> Crée un worktree depuis la branche actuelle
> start a worktree

Contrairement à la commande -w, les worktrees créés en session sont automatiquement basés sur la branche actuelle, et non sur la branche distante par défaut. Claude gère automatiquement la création du worktree et bascule dessus — aucune commande Git manuelle n'est nécessaire. Si vous travaillez déjà sur une branche feature, c'est l'approche la plus pratique — une simple phrase vous donne un environnement isolé basé sur votre branche actuelle.

Approche 3 : Créer avec -w d'abord, changer de branche en session

Créez d'abord un worktree avec claude -w, puis demandez à Claude de basculer vers la branche cible dans la session. L'inconvénient est qu'il extrait d'abord depuis la branche distante par défaut, puis bascule — une étape supplémentaire, moins propre que les deux premières approches. Et si la branche cible est déjà occupée par un autre worktree, vous rencontrerez un conflit de branche :

Comme le montre la capture d'écran, Claude détecte le conflit de branche et propose deux choix : revenir au répertoire principal, ou créer une nouvelle branche de travail basée sur la branche cible. Bien que cela fonctionne au final, le processus est moins direct que les approches 1 et 2.

Avancé : Encapsulation avec Makefile pour des commandes en un clic

Si vous avez fréquemment besoin de créer des worktrees depuis la branche actuelle, vous pouvez ajouter une commande raccourci dans le Makefile à la racine du projet, enchaînant création + ouverture de l'éditeur + lancement de Claude en un seul pipeline déterministe :

# Créer un worktree depuis la branche actuelle et lancer l'environnement de développement
# Utilisation : make worktree name=my-feature
worktree:
	@if [ -z "$(name)" ]; then \
		echo "Utilisation : make worktree name=<nom-du-worktree>"; \
		echo "Exemple : make worktree name=fix-login-bug"; \
		exit 1; \
	fi
	@echo "→ Création du worktree depuis $$(git branch --show-current) : $(name)"
	git worktree add -b $(name) .claude/worktrees/$(name) HEAD
	@echo "→ Initialisation de l'environnement"
	cd .claude/worktrees/$(name) && npm install
	@echo "→ Ouverture dans Zed"
	zed .claude/worktrees/$(name)
	@echo "→ Lancement de Claude"
	cd .claude/worktrees/$(name) && claude

L'utilisation est très simple :

# Créer un worktree depuis la branche actuelle, ouvrir dans Zed, lancer Claude
make worktree name=fix-login-bug

# Lancer plusieurs tâches en parallèle
make worktree name=feature-search
make worktree name=refactor-api

Par rapport à la saisie manuelle de plusieurs commandes Git/cd/claude, make worktree name=xxx ne nécessite qu'une seule ligne, et le processus est exactement le même à chaque fois — pas d'oubli d'étape ni d'erreur de chemin. Notez que le Makefile utilisant git worktree add natif, le Hook WorktreeCreate de Claude Code ne se déclenchera pas (ce Hook ne s'active qu'avec claude -w ou lors de la création de worktree en session). Les étapes d'initialisation de l'environnement (installation des dépendances, copie du .env, etc.) doivent donc être écrites directement dans le Makefile, comme dans l'exemple npm install ci-dessus.

Étape 2 : Initialiser l'environnement

Une fois le worktree créé, la première chose à faire est d'initialiser l'environnement de développement. Chaque nouveau worktree est un répertoire indépendant — node_modules, les environnements virtuels, les fichiers .env, etc. ne sont pas transférés automatiquement.

Claude Code fournit le Hook WorktreeCreate pour automatiser la configuration de l'environnement :

{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": "npm install && cp ../.env .env"
      }
    ]
  }
}

Ainsi, à chaque création de worktree, les dépendances sont automatiquement installées et le fichier de variables d'environnement est automatiquement copié. Étapes d'initialisation courantes :

Si les Hooks ne sont pas configurés, vous pouvez également exécuter /init au début de chaque session worktree pour vous assurer que Claude comprend correctement le contexte du répertoire de travail actuel et relit la structure du projet et la configuration CLAUDE.md.

Étape 3 : Commit et fusion

Une fois l'environnement prêt et le développement terminé, l'étape suivante est de fusionner les modifications vers la branche cible.

Fusion vers la branche main

Le cas le plus courant — le worktree a été créé depuis origin/main, et les modifications doivent être fusionnées vers main. Dans la session Claude du worktree, dites simplement :

> Commite toutes les modifications, pousse vers le dépôt distant, puis crée une PR vers main

Claude gère automatiquement l'ensemble du flux commit → push → gh pr create.

Fusion vers une branche feature

Si vous développez sur la branche feature-x et que les modifications du worktree doivent être fusionnées vers feature-x plutôt que main :

> Commite et pousse les modifications, puis crée une PR ciblant la branche feature-x

Claude exécutera gh pr create --base feature-x, créant directement une PR vers la branche feature.

Vous pouvez également quitter la session worktree (en choisissant de conserver le worktree), puis revenir au répertoire principal et lancer Claude :

> Fusionne les modifications de la branche worktree-my-task dans la branche actuelle

Si certains commits du worktree ne vous intéressent pas, vous pouvez les sélectionner avec cherry-pick :

> Montre-moi l'historique des commits de la branche worktree-my-task, puis cherry-pick les commits liés au module d'authentification vers la branche actuelle

Astuce : Tous les worktrees partagent la même base de données .git — les commits créés dans un worktree sont immédiatement visibles dans le répertoire principal, sans nécessiter d'opérations push/pull supplémentaires.

Étape 4 : Sortie et nettoyage

Une fois les modifications fusionnées, vous pouvez quitter la session worktree.

Lors de la sortie d'une session worktree, Claude gère automatiquement les choses selon l'état :

Les worktrees conservés persistent pour que vous puissiez continuer à travailler dessus ultérieurement.

Vous pouvez également configurer un Hook WorktreeRemove pour automatiser le nettoyage :

{
  "hooks": {
    "WorktreeRemove": [
      {
        "command": "echo 'Worktree cleaned up'"
      }
    ]
  }
}

Commandes de gestion manuelle

Si vous devez gérer manuellement les worktrees, utilisez les commandes Git standard :

# Lister tous les worktrees
git worktree list

# Supprimer manuellement un worktree
git worktree remove .claude/worktrees/feature-auth

# Nettoyer les références de worktree obsolètes
git worktree prune

Attention : Ne supprimez pas directement un répertoire worktree avec rm -rf. La bonne méthode est d'utiliser git worktree remove, ou si vous l'avez déjà supprimé par erreur, exécutez git worktree prune pour nettoyer les références résiduelles.

Modes de développement parallèle

Maintenant que vous maîtrisez le flux de travail de base, voyons comment exploiter les worktrees pour le développement parallèle.

Parallélisme multi-terminaux

L'utilisation la plus courante est l'exécution simultanée dans plusieurs onglets de terminal :

# Terminal 1 : Travailler sur l'authentification utilisateur
claude -w feature-auth

# Terminal 2 : Corriger un bug de paiement
claude -w bugfix-payment

# Terminal 3 : Refactoriser le module API
claude -w refactor-api

Chaque instance de Claude travaille dans son propre worktree sans interférer avec les autres. Vous pouvez :

• Laisser Claude développer une nouvelle fonctionnalité dans un terminal
• Laisser Claude corriger un bug dans un autre terminal
• Continuer votre propre revue de code dans un troisième terminal

Implémentation compétitive

Une utilisation efficace consiste à faire implémenter la même fonctionnalité indépendamment par plusieurs Agents :

# Trois terminaux exécutés séparément
claude -w feature-search-v1
claude -w feature-search-v2
claude -w feature-search-v3

Donnez-leur les mêmes spécifications et laissez chacun implémenter de manière indépendante. Ensuite, comparez les trois solutions et fusionnez la meilleure. Cela exploite le non-déterminisme des LLM — la même entrée peut produire des résultats différents, et parfois la deuxième version est meilleure.

L'exploration de design UI est également très adaptée à ce mode. Supposons que vous souhaitiez repenser l'interface de votre application, mais que vous ne sachiez pas quel style convient le mieux :

# Trois Agents implémentent différents styles
claude -w ui-minimal    # Style minimaliste
claude -w ui-colorful   # Couleurs vives
claude -w ui-glassmorphism  # Style glassmorphisme

Une fois terminé, exécutez simultanément les trois serveurs de développement (sur des ports différents), comparez côte à côte et fusionnez votre solution préférée dans la branche principale — bien plus efficace que le cycle traditionnel « construire une version, examiner, reconstruire ».

Isolation de Subagent

Les worktrees ne sont pas réservés à l'instance Claude principale — ils fonctionnent également avec les Subagents. Ajoutez isolation: worktree dans le frontmatter de votre Subagent personnalisé :

---
name: code-migrator
description: Handles large-scale code migrations. Use for batch refactoring.
tools: Read, Write, Edit, Bash, Grep, Glob
isolation: worktree
---

You are a code migration specialist...

Vous pouvez également le dire directement à Claude dans la conversation :

> utilise des worktrees pour tes agents
> use worktrees for your agents

Lorsqu'un Subagent est configuré avec l'isolation worktree :

Agent principal (répertoire principal)
│
├── Lancement Agent Migration 1 ──→ worktree-migration-1/
│   └── Traitement de src/auth/
│
├── Lancement Agent Migration 2 ──→ worktree-migration-2/
│   └── Traitement de src/api/
│
└── Lancement Agent Migration 3 ──→ worktree-migration-3/
    └── Traitement de src/utils/

Chaque Subagent travaille indépendamment dans son propre worktree sans interférence. Une fois terminé, le worktree est automatiquement nettoyé (s'il n'y a pas de modifications non commitées).

Intégration avec Tmux et l'IDE

Le paramètre --tmux lance automatiquement Claude dans une nouvelle session Tmux, pour qu'il continue de fonctionner même si vous fermez le terminal :

claude -w feature-auth --tmux

Si vous utilisez VS Code ou Cursor, le panneau de contrôle de code source reconnaît automatiquement tous les worktrees — le dépôt principal apparaît comme un repo, chaque worktree comme un repo indépendant, et vous pouvez basculer, commiter et pousser directement depuis l'IDE. Les worktrees peuvent également être combinés avec les boucles Ralph — chaque boucle Ralph s'exécute dans son propre worktree, de sorte que même une boucle échouée n'affecte pas la branche principale.

Conseils et bonnes pratiques

Pièges courants

1. Confusion sur l'origine de la branche : -w crée des worktrees depuis la branche distante par défaut, pas votre branche actuelle. Si vous exécutez claude -w my-task alors que vous êtes sur la branche feature-x, le code du nouveau worktree provient de origin/main et n'inclura pas les modifications de feature-x. Pour travailler depuis votre branche actuelle, consultez Création depuis la branche actuelle/spécifique.
2. Les modifications non commitées ne sont pas transférées : Lors de la création d'un worktree, les modifications non indexées ou non commitées du répertoire principal n'apparaîtront pas dans le nouveau worktree. Les worktrees sont créés uniquement à partir de l'historique des commits, alors assurez-vous de commiter les modifications importantes d'abord.
3. Une même branche ne peut pas être utilisée par plusieurs worktrees : Git ne permet pas à deux worktrees d'extraire simultanément la même branche. Si votre répertoire principal est déjà sur feature-x, tenter d'extraire feature-x dans un worktree échouera. Chaque worktree doit être sur une branche différente.
4. L'environnement nécessite une réinitialisation : Chaque nouveau worktree n'inclut pas les dépendances d'exécution comme node_modules. Configurez un Hook WorktreeCreate pour automatiser cette étape (voir Étape 2 : Initialiser l'environnement).

Recommandations d'utilisation

N'en abusez pas. Bien que techniquement vous puissiez ouvrir de nombreux worktrees, chaque instance de Claude consomme des crédits API, trop de tâches parallèles deviennent difficiles à suivre, et les conflits de fusion se complexifient.

Conventions de nommage : Adoptez de bonnes habitudes de nommage pour faciliter la gestion :

# Bon nommage
claude -w feature-user-auth
claude -w bugfix-payment-123
claude -w refactor-api-v2

# Mauvais nommage
claude -w test
claude -w temp
claude -w 1

Systèmes de versionnement non-Git

Si vous utilisez SVN, Perforce ou Mercurial, vous pouvez obtenir un effet d'isolation similaire en configurant les Hooks WorktreeCreate et WorktreeRemove. Une fois configurés, l'utilisation de --worktree invoquera vos commandes personnalisées au lieu du comportement Git par défaut.

Conclusion

Worktree est une fonctionnalité que l'équipe Claude Code utilise au quotidien — Boris Cherny la qualifie de « conseil de productivité numéro un ». La valeur fondamentale est simple : permettre à plusieurs Agents de travailler en parallèle sans interférer les uns avec les autres.

Pour commencer, c'est très simple :

claude -w your-task-name

Lectures complémentaires :

• Guide complet de Claude Subagent — Comprendre l'intégration entre Subagent et Worktree
• Analyse approfondie de Ralph Wiggum — Une autre approche pour améliorer l'efficacité de la programmation IA
• Architecture système de Claude expliquée — Comprendre la place de Worktree dans l'architecture globale

Références :

• Documentation officielle Claude Code - Common Workflows
• Annonce Worktree de Boris Cherny
• Documentation officielle Git Worktree
• incident.io - Shipping faster with Claude Code and Git Worktrees
• Dev.to - Git worktree + Claude Code: My Secret to 10x Developer Productivity

Tutoriels vidéo :

• I'm using claude --worktree for everything now — Démonstration complète du flux de travail worktree
• Git Worktrees: The secret sauce to Claude Code! — Méthodes de création manuelle de worktree
• Native Worktrees Just Killed Traditional Claude Code Workflows — Présentation détaillée de la fonctionnalité worktree native
• Claude Code Worktrees in 7 Minutes — Tutoriel de prise en main rapide, incluant l'utilisation avec Subagent
• Stop Using Claude Code on One Branch — Avantages du développement parallèle multi-worktree