Il y a quelques semaines, j’ai écrit un article sur les git worktrees — ce que c’est, comment les créer, pourquoi ils sont mieux que cloner le repo trois fois. Les bases.

Mais les bases, ce n’est que la moitié de l’histoire. Claude Code ne se limite pas à fonctionner sur les worktrees — il les prend en charge nativement. Des flags dédiés, un isolement automatique, une intégration avec tmux. Et la différence entre savoir que les worktrees existent et comprendre comment Claude Code les exploite, c’est comme avoir une voiture et découvrir qu’elle a un mode sport.

Boris Cherny, le créateur de Claude Code, a publié un thread avec cinq astuces pour en profiter pleinement. Je les ai toutes testées. Certaines ont transformé mon workflow. D’autres m’ont évité les bidouilles que je faisais depuis janvier. Voyons-les ensemble.

Astuce 1 : --worktree — un worktree avec un seul flag

Le flux classique pour travailler avec un worktree est :

1
2
3

git worktree add ../mon-projet-feature -b feature/quelque-chose
cd ../mon-projet-feature
claude

Trois étapes. Ce n’est pas dramatique, mais cela implique de réfléchir aux noms des dossiers, se souvenir de la syntaxe, et ensuite de naviguer vers le nouveau dossier. Si tu fais ça cinq fois par jour, c’est fatigant.

Claude Code réduit tout cela à une seule commande :

1

claude --worktree

C’est tout. Claude crée un worktree temporaire dans un répertoire avec un nom généré automatiquement, s’y déplace, et démarre une session. Une fois terminé, le worktree est nettoyé.

Quand est-ce que je l’utilise ? Chaque fois que je veux essayer quelque chose sans polluer ma branche actuelle. Faire une refactorisation agressive, explorer une alternative de conception, ou faire un prototype rapide. Si ça fonctionne, je merge. Sinon, tout disparaît sans laisser de trace.

C’est l’équivalent d’ouvrir un brouillon dans ton éditeur de texte. Sans engagement, sans cérémonie.

Astuce 2 : sous-agents dans des worktrees isolés

Si tu utilises déjà des sous-agents dans Claude Code (avec Task à l’intérieur d’un agent personnalisé ou avec l’agent principal déléguant), tu sais qu’ils partagent le répertoire de travail. Cela signifie que deux sous-agents peuvent écraser les fichiers, se disputer l’index de git, ou laisser la zone de staging dans un état chaotique.

La solution : des sous-agents qui fonctionnent chacun dans leur propre worktree.

Lorsque qu’un agent lance un sous-agent avec isolation de worktree, Claude Code :

  1. Crée un worktree temporaire pour le sous-agent.
  2. Le sous-agent y travaille, dans sa propre branche.
  3. Une fois terminé, les modifications peuvent être mergées dans le worktree parent.
  4. Le worktree temporaire est nettoyé.

Dit en langage clair : chaque sous-agent a son propre espace de travail. Ils peuvent scier du bois en même temps sans risquer de se couper mutuellement les doigts.

Le bénéfice n’est pas seulement d’éviter les conflits. C’est que tu peux paralléliser vraiment. Envoyer un sous-agent écrire des tests pendant qu’un autre implémente une fonctionnalité. L’un traduit la documentation pendant que l’autre refactorise le module d’authentification. Sans attente, sans blocage.

Astuce 3 : agents personnalisés avec isolation: worktree

C’est là où cela devient vraiment intéressant. Les agents personnalisés dans Claude Code se définissent avec un fichier Markdown dans .claude/agents/. Et dans le frontmatter de ce fichier, tu peux mettre :

1
2
3
4

---
name: refactor-module
isolation: worktree
---

isolation: worktree indique à Claude Code : “à chaque invocation, donne à cet agent son propre worktree automatiquement”. Pas besoin de passer --worktree. Pas besoin de créer quoi que ce soit manuellement. L’isolation fait partie de la définition de l’agent.

Pourquoi est-ce utile ? Pour les agents qui, par conception, devraient toujours travailler isolés. Quelques exemples :

Un agent de refactorisation agressive. Tu veux un agent qui déplace des fichiers, renomme des fonctions, change la structure des répertoires. Si tu fais cela dans ta branche de travail, toute erreur devient catastrophique. Avec isolation: worktree, l’agent fait les modifications dans sa propre copie. Tu révises le diff. Si ça te convainc, tu merges. Sinon, git worktree remove comme si rien ne s’était passé.

Un agent de traduction. Je l’utilise littéralement pour ce blog. Un agent qui traduit des articles en quatre langues, génère le frontmatter, et commit. Il a besoin de modifier plusieurs fichiers en même temps. S’il opère dans mon répertoire de développement, cela me bloque. Dans son propre worktree, il traduit pendant que je continue à écrire le prochain article.

Un agent de migration de base de données. Génère des fichiers SQL, les valide par rapport au schéma actuel, et exécute des tests. Tout dans un worktree isolé où il peut “casser des choses” sans conséquences.

La clé, c’est que isolation: worktree fait de l’isolation un attribut de l’agent, plutôt qu’une décision à prendre à chaque fois que tu le lances. C’est comme passer d’une voiture qui a des airbags à une voiture où tu dois toujours te rappeler d’activer la sécurité avant chaque trajet.

Astuce 4 : --tmux — des sessions parallèles automatisées

Avant, “parallèle” signifiait ouvrir plusieurs terminaux manuellement. Terminal 1 pour un worktree, terminal 2 pour un autre, terminal 3 pour le principal. Ça fonctionnait, mais c’était artisanal.

--tmux automatise tout cela :

1

claude --worktree --tmux

Claude Code crée le worktree, lance la session dans un panneau tmux, et te rend le contrôle de ton terminal. Tu peux lancer trois, quatre, ou cinq sessions ainsi :

1
2
3

claude --worktree --tmux  # session 1 : développer une fonctionnalité A
claude --worktree --tmux  # session 2 : écrire des tests pour le module B
claude --worktree --tmux  # session 3 : refactoriser le CLI

Chaque session dans son propre worktree, chaque session dans un panneau tmux, toutes fonctionnant en parallèle. Tu bascules entre elles avec Ctrl-b + numéro de fenêtre (ou ton raccourci tmux préféré).

C’est le game changer pour les sprints de productivité. Imagine un lundi matin : tu ouvres ton backlog, sélectionnes trois tâches indépendantes, et lances trois agents. Pendant que l’un écrit des tests, un autre implémente une fonctionnalité, et le troisième met à jour la documentation. Tu supervises, révises les diffs lorsqu’ils se terminent, et merges.

Ce n’est pas de la science-fiction. C’est juste un flag.

Astuce 5 : quand NE PAS utiliser les worktrees

Savoir quand utiliser les worktrees est aussi important que savoir quand ne pas les utiliser. Boris Cherny le dit explicitement, et je suis d’accord.

Ne les utilise pas pour des tâches séquentielles. Si la tâche B dépend des résultats de la tâche A, tu ne gagnes rien à paralléliser. Au contraire, tu perds : maintenant, tu dois merger A avant que B puisse commencer, ajoutant des étapes inutiles.

Ne les utilise pas pour des modifications mineures. Une correction d’une ligne ne justifie pas le cérémonial de créer un worktree, même si --worktree le réduit à un flag. L’effort mental d’avoir plusieurs répertoires actifs ne compense pas un changement rapide.

Ne les utilise pas si les changements touchent les mêmes fichiers. Si la fonctionnalité A et la fonctionnalité B doivent toutes deux modifier le même config.toml ou le même routes.py, tu te prends un conflit au merge à coup sûr. Les worktrees brillent lorsqu’ils concernent des fonctionnalités orthogonales — modifiant des zones distinctes du code.

Ne les utilise pas sans un plan. Lancer cinq agents en parallèle “pour voir” semble productif. Mais en pratique, cela finit avec cinq branches dans des états variés, cinq diffs à examiner, et cinq merges potentiellement conflictuels. La parallélisation fonctionne avec une intention claire : des tâches indépendantes et des critères d’acceptation définis.

La règle d’or : si tu peux décrire chaque tâche en une phrase et qu’aucune ne dépend d’une autre, utilise les worktrees. Sinon, travaille en série.

Le workflow complet : de la théorie à ton lundi matin

Pour résumer, voici le processus que j’utilise maintenant, lorsque j’ai plusieurs tâches indépendantes dans mon backlog :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# 1. Vérifie le backlog et sélectionne des tâches indépendantes
linear issue list --team PROD --state unstarted --sort priority --no-pager

# 2. Démarre un agent par tâche, chacun dans son worktree + tmux
claude --worktree --tmux  # "implémente la fonctionnalité X, crée des tests"
claude --worktree --tmux  # "refactorise le module Y"
claude --worktree --tmux  # "traduit les articles en attente"

# 3. Examine les progrès au fur et à mesure (panneaux tmux)
# Ctrl-b + 1, 2, 3 pour basculer entre les sessions

# 4. Examine le diff de chaque worktree
cd /tmp/claude-worktree-abc123  # ou où Claude l’a créé
git diff main

# 5. Si le diff est convaincant, push + PR
git push -u origin feature/quelque-chose
# PR, review, merge

# 6. Nettoyage (ou laisser Claude le faire automatiquement)
git worktree list  # voir ce qui reste actif

Ce qui avant me prenait tout une matinée — développer trois fonctionnalités, les tester et ouvrir des PR — peut maintenant être terminé avant d’aller boire une bière.

L’évolution : du manuel au natif

Au début avec les worktrees il y a quelques semaines, tout était manuel. git worktree add, cd, claude, ouvrir un autre terminal, répéter. Ça fonctionnait, mais cela donnait l’impression de monter une tente chaque fois que tu voulais profiter de ton jardin.

Avec --worktree, isolation: worktree, et --tmux, Claude Code a rendu les worktrees presque invisibles. On n’y pense pas. On ne les gère pas. On dit simplement “travaille en parallèle” et l’outil s’occupe du reste.

C’est la même évolution que nous avons vue avec les conteneurs : d’abord tout manuellement avec LXC, puis Docker a simplifié le processus, et maintenant on ne pense même plus aux namespaces du kernel. Les worktrees sont à cette phase d’abstraction. Git a posé les bases en 2015. Onze ans plus tard, l’outillage les rend enfin invisibles.

Et au final, c’est ce qu’on attend de tout bon outil : qu’il fasse son travail puis qu’il disparaisse.

TL;DR : Claude Code propose cinq fonctionnalités clés pour les worktrees : --worktree (créer et entrer dans un worktree avec un flag), sous-agents isolés (chacun dans un worktree), isolation: worktree dans les agents personnalisés (isolement par design), --tmux (sessions parallèles automatisées), et savoir quand ne pas les utiliser. Résultat : un vrai parallélisme sans gestion manuelle. Les worktrees passent d’être une fonction git peu exploitée à devenir l’infrastructure invisible de ton workflow avec des agents.