Travailler en parallèle avec les worktrees

1Laisser Claude Code créer le worktree

Le plus simple : passer --worktree (ou -w) avec un nom.

claude --worktree feature-auth

Par défaut, le worktree est créé sous .claude/worktrees/<nom>/ à la racine du dépôt, sur une nouvelle branche nommée worktree-<nom>. Relance la même commande avec un autre nom dans un second terminal pour ouvrir une deuxième session isolée. Sans nom, Claude Code en génère un du genre bright-running-fox.

Ajoute le dossier à ton .gitignore pour que les worktrees n'apparaissent pas comme fichiers non suivis dans ton dépôt principal :

.claude/worktrees/

Un point à connaître : les lancements interactifs demandent la confiance de l'espace de travail. Si tu n'as jamais lancé claude dans ce dossier, --worktree sort en erreur en te demandant de le faire une fois.

2Préparer l'environnement du worktree

Un worktree est une copie fraîche : node_modules, .venv et .env n'y sont pas. Les dépendances, tu les installes (ou tu demandes à Claude de le faire).

Pour les fichiers ignorés par git, il y a un mécanisme dédié : un fichier .worktreeinclude à la racine du projet, en syntaxe .gitignore.

.env
.env.local
config/secrets.json

Seuls les fichiers qui correspondent à un motif et sont ignorés par git sont copiés, donc les fichiers suivis ne sont jamais dupliqués. Ça s'applique à tous les worktrees créés par Claude Code avec git.

3Choisir la branche de départ

Par défaut, un nouveau worktree part de la branche par défaut du dépôt distant, généralement main. C'est le bon choix pour une tâche neuve, et le mauvais quand tu veux travailler sur ce que tu as en cours.

Dans tes réglages :

{
  "worktree": {
    "baseRef": "head"
  }
}

"fresh" (le défaut) part de la branche par défaut distante, "head" de ton HEAD local, donc avec tes commits non poussés. Le réglage n'accepte pas un nom de branche : pour partir d'une branche précise, crée le worktree avec git directement.

Pour partir d'une pull request, --worktree accepte son numéro préfixé de #, ou une URL GitHub complète. Pense à protéger le # de ton shell :

claude --worktree "#1234"

4Isoler aussi les sous-agents

Un sous-agent peut tourner dans son propre worktree. Pour le rendre permanent, ajoute isolation: worktree au frontmatter, dans .claude/agents/ :

---
name: refactorer
description: Applique des refactors mecaniques sur de nombreux fichiers
isolation: worktree
---

Applique le refactor demande sur tous les fichiers concernes, puis lance les
tests et rapporte les resultats.

Le worktree temporaire est supprimé automatiquement si le sous-agent ne produit aucun changement. S'il en produit, il reste sur le disque jusqu'à ce qu'un balayage périodique puisse le retirer sans perdre de travail.

5Nettoyer

À la sortie d'une session interactive, Claude Code vérifie si le worktree contient du travail : fichiers modifiés ou non suivis, nouveaux commits.

• Worktree propre, session sans nom : supprimé automatiquement, branche comprise.
• Worktree propre, session nommée : on te demande d'abord.
• Worktree avec du travail dedans : on te demande de garder ou de supprimer. Supprimer efface le dossier, la branche, et tout ce qu'ils contiennent.

Les lancements non interactifs avec -p n'ont pas d'invite de sortie, donc personne ne nettoie derrière eux :

git worktree remove .claude/worktrees/feature-auth

Ajoute --force si le worktree a des modifications non commitées ou des fichiers non suivis.