Comment exécuter plusieurs agents Claude Code en parallèle

TL;DR : Pour exécuter plusieurs agents Claude Code en parallèle, attribuez à chaque session son propre worktree git (l'option claude -w <name> s'en charge directement), basculez en arrière-plan les sessions que vous ne surveillez pas avec claude --bg, et déterminez l'ordre de fusion avant que les agents ne terminent, car des branches isolées finissent tout de même par entrer en conflit lors de l'intégration. Lorsque deux sessions partagent le même checkout, le commit d'un agent se retrouve inévitablement avec le code à moitié rédigé de l'autre. Ce guide s'adresse aux développeurs qui utilisent déjà Claude Code et souhaitent faire tourner de deux à cinq sessions simultanément.

Tout commence avec un deuxième terminal. Claude Code est en train de refactoriser le module d'authentification dans le premier, alors vous en ouvrez un autre et demandez à une nouvelle session de corriger ce test de date instable. Puis un troisième pour la documentation. Vingt minutes plus tard, trois sessions écrivent dans le même répertoire de travail, git status affiche des fichiers que vous n'avez aucun souvenir d'avoir demandés, et personne ne peut dire quelle session a modifié config.ts.

Lancer plusieurs agents Claude Code est simple : il suffit d'ouvrir d'autres terminaux. Mais les faire tourner sans que les sessions ne corrompent mutuellement leur travail exige trois décisions : où résident les fichiers de chaque session, comment suivre les sessions que vous n'avez pas sous les yeux, et dans quel ordre intégrer leurs branches. Cet article aborde ces trois points à l'aide des commandes intégrées de Claude Code et de deux cas d'échec reproduits sur un dépôt de test. Si vous découvrez les worktrees, lisez d'abord notre guide des git worktrees avec les agents de code IA ou la documentation de référence de git worktree.

Pourquoi plusieurs agents Claude Code corrompent un checkout partagé

Exécuter plusieurs agents Claude Code en parallèle signifie que deux sessions ou plus travaillent sur le même dépôt en même temps, chacune avec sa propre tâche et sa propre fenêtre de contexte. Les sessions n'ont pas conscience les unes des autres. Chacune lit des fichiers, les modifie, exécute les tests et commite comme si elle était seule au monde.

Un checkout ne possède qu'un seul répertoire de travail, un seul index et un seul HEAD, si bien que l'illusion d'être « seul » tourne vite court. Nous avons reproduit le scénario le plus courant sur un petit dépôt Python de test, avec deux scripts shell simulant les agents. L'agent B enregistre une fonction truncate() à moitié écrite dans textutils.py. L'agent A termine sa propre tâche dans un autre fichier et effectue un commit comme beaucoup de prompts lui ordonnent de le faire, avec git add -A && git commit :

$ git show --stat --format='%an: %s' HEAD
agent-a: add slugify
 slug.py      | 2 ++
 textutils.py | 4 ++++
 2 files changed, 6 insertions(+)

$ python3 -m pytest -q
1 error in 0.09s

Le commit de l'agent A embarque la fonction inachevée de l'agent B, et la suite de tests échoue dès l'import. Rien n'a été écrasé. L'index étant partagé, le commit de A a englobé le travail en cours de B, et l'historique indique désormais que l'agent A a introduit du code cassé. La variante de ce problème sur un même fichier est détaillée dans ce qui se passe quand deux agents de code modifient le même fichier.

Exécuter plusieurs agents Claude Code avec un worktree dédié par session

La solution consiste à attribuer un répertoire de travail par session, et Claude Code propose cette fonctionnalité via une simple option :

# interactive sessions, one task each, each in its own worktree
claude -w auth-refactor
claude -w flaky-date-test --tmux   # opens the session in its own tmux or iTerm2 pane

# fire-and-forget work: starts in the background and prints an id
claude --bg "update the README examples for the new config format"

D'après la documentation sur les worktrees, claude -w <name> crée un worktree dans .claude/worktrees/<name>/ sur une nouvelle branche nommée worktree-<name>, et un second terminal utilisant un nom différent bénéficie d'une deuxième session isolée. Lors de nos tests, git a marqué le nouveau worktree comme locked, ce qui empêche git worktree prune de le supprimer pendant qu'une session est active. Les sessions en arrière-plan lancées avec --bg ou /bg basculent dans leur propre worktree sous .claude/worktrees/ avant toute modification de fichier, conformément à la page de la vue agents.

Trois détails de configuration vous éviteront de perdre un après-midi :

1. Ignorez le dossier. Les worktrees se trouvent à l'intérieur du dépôt, donc git status dans le checkout principal affiche .claude/ comme non suivi tant que vous n'ajoutez pas .claude/worktrees/ au .gitignore, ce que la documentation recommande d'ailleurs.
2. Préparez-vous à un checkout vierge. Un nouveau worktree ne contient aucun node_modules, environnement virtuel ou .env. Répertoriez les fichiers ignorés par git dont vous avez besoin (comme le fichier .env) dans un fichier .worktreeinclude, et prévoyez une étape d'installation des dépendances par worktree.
3. Nettoyez vous-même les exécutions non interactives. Les sessions interactives proposent de supprimer leur worktree lorsqu'elles se terminent. En revanche, les exécutions lancées avec claude -p ne font aucun nettoyage ; supprimez-les donc avec git worktree unlock suivi de git worktree remove.

Les sessions en arrière-plan se gèrent depuis le shell. Ces descriptions proviennent de claude --help sur la version 2.1.283 :

L'option --bg ne peut pas être combinée avec -p. Pour un traitement parallèle par script (fan-out), le guide d'utilisation de Claude Code d'Anthropic propose une boucle shell exécutant claude -p avec --allowedTools et --permission-mode dontAsk. Associez-lui -w afin que chaque exécution dispose de son propre répertoire.

Les agents Claude Code isolés entrent toujours en conflit au moment du merge

Les worktrees évitent que les sessions n'interfèrent entre elles pendant leur travail. Mais ils ne rendent pas leurs modifications compatibles pour autant. Nous avons appliqué le même type de modification sur deux branches de worktree distinctes, chacune ajoutant une fonction à la fin de textutils.py, puis nous avons fusionné les deux :

$ git merge agent/slugify
Fast-forward
$ git merge agent/truncate
Auto-merging textutils.py
CONFLICT (content): Merge conflict in textutils.py
Automatic merge failed; fix conflicts and then commit the result.

Aucun des deux agents n'a commis d'erreur. Tous deux ont ajouté du code au même endroit et git ne peut pas choisir l'ordre d'insertion à leur place. Sur une base de code réelle avec quatre ou cinq sessions en parallèle, c'est la situation habituelle pour tout fichier fréquemment sollicité : tables de routage, exports __init__.py, changelogs, lockfiles. La différence par rapport à un checkout partagé réside dans le fait que le conflit est désormais explicite, visible et attribuable. Trois bonnes pratiques permettent d'en limiter l'impact :

1. Découpez les tâches par fichier, et non par fonctionnalité. Deux tâches nécessitant toutes deux de toucher au routeur doivent former une seule tâche, ou être exécutées l'une après l'autre.
2. Fusionnez dans un ordre prédéfini et rebasez le reste. Intégrez la première branche, puis demandez à la session suivante de se rebaser sur main et de relancer ses tests avant votre revue. La session ayant rédigé le code dispose de tout le contexte pour résoudre son propre conflit.
3. Nommez chaque worktree d'après sa tâche. claude -w fix-date-test s'avère bien plus clair que claude -w agent2 quand vous consultez git worktree list une heure après.

Le véritable goulet d'étranglement n'est généralement pas git : c'est votre capacité à relire cinq diffs. Notre article expliquant pourquoi la revue humaine représente le véritable goulot d'étranglement pour les agents parallèles explique comment dimensionner cette file d'attente.

Sous-agents, équipes d'agents ou sessions distinctes pour exécuter plusieurs agents Claude Code

Claude Code propose désormais plusieurs approches pour paralléliser le travail, et la vue d'ensemble des agents parallèles les compare côte à côte. Elles ne sont pas interchangeables. Le critère le plus déterminant reste l'isolation :

Pour les tâches indépendantes, privilégiez des sessions distinctes avec des worktrees. Utilisez les équipes d'agents lorsque les éléments dépendent les uns des autres et que les coéquipiers doivent se coordonner, en attribuant des fichiers distincts à chacun. La page sur les équipes d'agents est en effet sans détour : « Deux coéquipiers modifiant le même fichier entraînent des écrasements de code. » Quel que soit votre choix, la consommation du quota est partagée. La documentation de la vue agents le formule clairement : « faire tourner dix agents en parallèle consomme votre quota environ dix fois plus vite qu'un seul. »

La place de Sharkly pour exécuter plusieurs agents Claude Code

Si vous faites tourner deux ou trois sessions sur votre propre ordinateur portable et relisez vous-même chaque diff, les commandes présentées ci-dessus suffisent amplement et vous n'avez probablement pas besoin de Sharkly. L'équation change dès lors que les sessions appartiennent à plusieurs personnes, ou que répondre à la question « quelle session contient le correctif du test de date ? » prend plus de temps que l'écriture du correctif lui-même.

Vous disposez déjà d'agents de code. Sharkly les transforme en une véritable équipe. Chaque unité de travail devient une Task. Vous l'assignez à un Agent qui s'exécute sur le Claude Code Runtime sur l'un de vos Computers, et définir l'Assignee déclenche l'exécution. Avec le répertoire de travail par défaut, Create temporary directory, chaque Task bénéficie de son propre répertoire et les exécutions adossées à un dépôt obtiennent un git worktree isolé : le même niveau d'isolation qu'avec claude -w, sans avoir à nommer les worktrees manuellement. Lorsqu'un Agent doit réutiliser un environnement déjà présent sur un Computer local, l'option Run in isolated worktrees livre le résultat de chaque Task sur sa propre branche agent/<agent>/<task>. Le paramètre Max concurrency (assigned tasks) sur l'Agent plafonne le nombre d'exécutions simultanées, matérialisant ainsi la limite de revue mentionnée plus haut à un endroit visible par toute l'équipe.

La progression, l'historique d'exécution et le résultat remontent dans la Task, et tout ce qui requiert une intervention humaine atterrit dans l'Inbox. Rien n'est fusionné automatiquement : un humain examine les modifications du worktree, les conserve, les fusionne ou les rejette, puis passe la Task à Done. Les exécutions sont toujours facturées sur votre propre forfait Claude Code, car Sharkly ne vend pas de tokens. La page des fonctionnalités Agents présente la configuration, et l'article sur la façon dont Sharkly exécute des agents en parallèle détaille l'aspect exécution.

Si vous avez dépassé le cap des trois terminaux et cherchez à rassembler le résultat de chaque session Claude Code en un lieu unique qu'un relecteur peut facilement traiter, c'est précisément le problème pour lequel Sharkly a été conçu.

FAQ

Combien d'agents Claude Code puis-je exécuter simultanément ? La documentation ne fixe aucune limite pour les sessions distinctes. Les sous-agents sont limités par défaut à 20 exécutions simultanées, et la page des équipes d'agents conseille de débuter avec 3 à 5 coéquipiers. Les limites pratiques dépendent de la consommation autorisée par votre forfait, du processeur et de la mémoire de votre ordinateur portable, ainsi que du volume de résultats que vous êtes capable de relire par jour ; le calcul de la capacité de revue par journée de travail mérite d'être posé avant de lancer une sixième session.

Les sessions Claude Code en parallèle partagent-elles mes limites d'utilisation ? Oui. Avec les forfaits Pro et Max, les limites d'utilisation sont partagées entre Claude et Claude Code, avec une fenêtre glissante de cinq heures et un plafond hebdomadaire, et chaque session parallèle puise dans la même réserve. Si la variable ANTHROPIC_API_KEY est définie, Claude Code facture directement sur l'API.

L'option claude --worktree copie-t-elle mon .env et mes dépendances ? Non. Chaque worktree correspond à un checkout vierge. Ajoutez les fichiers ignorés par git dont vous avez besoin, comme .env, dans .worktreeinclude, et lancez l'étape d'installation dans chaque worktree.

Puis-je exécuter Claude Code et Codex en parallèle sur le même dépôt ? Oui, en suivant la même règle : un worktree par session et un ordre de fusion bien défini. Notre guide sur l'exécution conjointe de Claude Code et Codex sur une même base de code détaille la partie routage.