Claude Code Worktree : Lance des Sessions Parallèles Sans Conflits Git

Mis à jour le 3 mars 2026

Tu es en plein développement d'une feature. Ton code est à moitié modifié, rien n'est commité. Et là, un bug critique en production. Tu dois intervenir maintenant. Classiquement, c'est le scénario du git stash : tu sauvegardes ton travail en cours, tu switch de branche, tu fixes le bug, tu reviens, tu restaures ton stash. Et tu pries pour ne rien avoir cassé.

Avec les worktrees dans Claude Code, tu ouvres simplement une session parallèle isolée. Ton travail en cours reste intact dans ta session principale. Le bug se règle dans un espace séparé, avec sa propre branche, son propre répertoire, sa propre session Claude Code. Aucune interférence. Zéro stress.

Si tu découvres Claude Code, commence par le guide complet pour maîtriser les bases avant de plonger dans les worktrees.

C'est quoi un worktree dans Claude Code ?

Un worktree, c'est une copie isolée de ton repository git. Pas un clone complet — une copie légère qui partage le même historique git mais possède son propre répertoire de travail et sa propre branche. Pense à ça comme un bureau supplémentaire dans ton atelier : tu peux étaler un second projet sans ranger le premier.

Dans Claude Code, les worktrees sont créés dans le dossier .claude/worktrees/ à la racine de ton projet. Chaque worktree obtient automatiquement une nouvelle branche basée sur ton HEAD actuel (le commit sur lequel tu te trouves au moment de la création). Tout ce que tu fais dans un worktree — modifications de fichiers, nouveaux commits, exécution de commandes — reste dans cet espace. Ton répertoire principal n'est pas touché.

La différence avec une branche git classique est fondamentale. Une branche est juste un pointeur vers un commit. Pour travailler dessus, tu dois faire un git checkout qui modifie tes fichiers en place. Un worktree, lui, crée un répertoire physique séparé. Tu peux avoir ta branche main ouverte dans ton répertoire principal ET une branche fix/bug-urgent ouverte dans un worktree, les deux en même temps, sans aucun switch.

Comment lancer un worktree

Trois façons de créer un worktree dans Claude Code, selon ton contexte.

Depuis le terminal, au lancement :

claude --worktree fix-urgent

Le raccourci -w marche aussi. Claude Code crée le worktree dans .claude/worktrees/fix-urgent/, crée une branche dédiée, et ouvre la session directement dans ce répertoire isolé. Si tu ne donnes pas de nom, un nom aléatoire est généré.

Depuis une session interactive :

/worktree

Tu es déjà dans une session Claude Code et tu veux basculer dans un worktree sans quitter. La commande /worktree crée l'espace isolé et déplace ta session dedans. Pratique quand tu réalises en cours de route que tu as besoin d'un espace séparé.

Avec un nom explicite :

claude -w refactor-auth
claude --worktree test-approche-b

Nommer ses worktrees est une bonne habitude. Quand tu en as deux ou trois ouverts, fix-urgent est plus parlant que worktree-7f3a.

Chaque worktree est indépendant. Les modifications dans un worktree n'affectent ni le répertoire principal, ni les autres worktrees. Tu travailles dans des espaces étanches.

3 cas d'usage concrets

1. Bug urgent pendant le développement d'une feature

Le scénario classique. Tu es en plein milieu d'une feature complexe — 15 fichiers modifiés, rien de commité, tout en état intermédiaire. Un bug critique en production arrive. Avec git stash, tu risques des conflits au retour. Avec un worktree :

claude -w fix-prod-bug-42

Tu ouvres une session dans un espace propre, sur une branche fraîche basée sur main. Tu fixes le bug, tu commit, tu fais ta PR. Tu fermes le worktree. Ta feature en cours n'a jamais été touchée. Zéro risque.

2. Tester une approche alternative

Tu hésites entre deux implémentations d'un même système. Plutôt que de coder la première, la supprimer si elle ne convient pas, puis coder la seconde — ouvre deux worktrees :

claude -w approche-rest-api
claude -w approche-graphql

Deux sessions parallèles, deux implémentations. Tu compares les résultats, tu gardes la meilleure, tu supprimes l'autre. C'est du prototypage parallèle, et ça divise le temps de décision par deux.

3. Travail en équipe sur des branches séparées

Si tu travailles avec d'autres développeurs (ou avec plusieurs sessions Claude Code en mode team), chaque participant peut avoir son propre worktree. Chacun travaille sur sa branche sans risque de conflit dans le répertoire de travail. Les merges se font proprement via git, pas via des fichiers écrasés.

Worktrees et sub-agents

Là où les worktrees deviennent vraiment puissants, c'est quand tu les combines avec les sub-agents. Par défaut, un sub-agent travaille dans le même répertoire que ta session principale. Mais tu peux configurer un agent custom pour qu'il travaille automatiquement dans un worktree isolé grâce à la propriété isolation.

---
name: refactor-agent
description: Refactoring isolé dans un worktree dédié
model: opus
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
isolation: "worktree"
---

Tu es un agent de refactoring. Tu travailles dans un worktree isolé.
Analyse le code, applique les modifications, commit le résultat.
Le code principal n'est jamais affecté tant que le merge n'est pas validé.

Avec isolation: "worktree", chaque fois que cet agent est lancé, il travaille dans sa propre copie du repo. Il peut modifier des fichiers, exécuter des commandes, commiter — tout ça sans toucher à ton répertoire principal. Si le résultat te convient, tu merges. Sinon, tu supprimes le worktree et c'est comme s'il ne s'était rien passé.

C'est particulièrement utile dans le contexte des team agents. Un leader peut distribuer des tâches à plusieurs agents, chacun isolé dans son propre worktree. Aucun risque de conflit de fichiers entre agents. Chaque agent produit son résultat sur sa branche, et les merges se font après validation.

Tu peux aussi utiliser cette mécanique pour du Plan Mode avancé : planifier dans ta session principale, puis déléguer l'exécution à un agent isolé dans un worktree. Si l'implémentation ne convient pas, tu jettes le worktree sans avoir touché à ton code.

Bonnes pratiques

Nomme tes worktrees. Toujours. claude -w fix-auth-bug plutôt que claude -w. Quand tu as trois worktrees ouverts, un nom clair te fait gagner du temps. Utilise le même format que tes branches : fix/description, feature/description, test/description.

Nettoie régulièrement. Les worktrees sans changements sont nettoyés automatiquement à la fin de session. Mais les worktrees avec des modifications restent. Vérifie périodiquement ton dossier .claude/worktrees/ et supprime ceux qui ne servent plus. Un worktree oublié depuis deux semaines, c'est du bruit inutile.

N'en abuse pas. Deux ou trois worktrees simultanés, c'est productif. Dix worktrees ouverts, c'est du chaos. Chaque worktree est un contexte à gérer mentalement. Reste raisonnable — l'objectif est la clarté, pas la multiplication.

Merge proprement. Quand ton travail dans un worktree est terminé, fais une vraie PR ou un merge propre. Ne copie-colle pas les fichiers d'un worktree à l'autre. Git est là pour ça : git merge, git rebase, ou une pull request. Le worktree a sa propre branche — utilise-la.

Utilise l'isolation pour les tâches risquées. Refactoring massif, mise à jour de dépendances, migration de base de données — tout ce qui pourrait casser ton code. Fais-le dans un worktree. Si ça fonctionne, merge. Si ça casse, supprime. C'est un filet de sécurité gratuit.

Pour aller plus loin dans l'organisation de tes sessions, le guide sur les hooks d'automatisation explique comment déclencher des actions automatiques au démarrage et à la fermeture de session. Et si tu rencontres des problèmes, le guide de debug couvre les erreurs courantes.

Meydeey

Architecte IA & Automatisation · Fondateur LE LABO IA · +25 000 abonnés YouTube