Orchestrer des équipes de sessions Claude Code

Coordonnez plusieurs instances Claude Code travaillant ensemble en tant qu'équipe, avec des tâches partagées, la messagerie inter-agents et la gestion centralisée.

Les équipes d'agents vous permettent de coordonner plusieurs instances Claude Code travaillant ensemble. Une session agit comme chef d'équipe, coordonnant le travail, assignant des tâches et synthétisant les résultats. Les coéquipiers travaillent indépendamment, chacun dans sa propre fenêtre de contexte, et communiquent directement les uns avec les autres. Vous pouvez également parler directement à n'importe quel coéquipier sans passer par le chef.

Avant de configurer une équipe, vérifiez si une option plus légère fait le travail. Les subagents fonctionnent au sein d'une seule session, et avec la messagerie inter-sessions, Claude peut transmettre les résultats entre les sessions que vous exécutez vous-même.

Quand utiliser les équipes d'agents

Les équipes d'agents sont les plus efficaces pour les tâches où l'exploration parallèle ajoute une réelle valeur. Consultez les exemples de cas d'usage pour des scénarios complets. Les cas d'usage les plus solides sont :

• Recherche et examen : plusieurs coéquipiers peuvent enquêter sur différents aspects d'un problème simultanément, puis partager et contester les conclusions les uns des autres
• Nouveaux modules ou fonctionnalités : les coéquipiers peuvent chacun posséder une partie distincte sans se marcher dessus
• Débogage avec hypothèses concurrentes : les coéquipiers testent différentes théories en parallèle et convergent vers la réponse plus rapidement
• Coordination inter-couches : les modifications qui s'étendent sur le frontend, le backend et les tests, chacun possédé par un coéquipier différent

Les équipes d'agents ajoutent une surcharge de coordination et utilisent considérablement plus de tokens qu'une seule session. Elles fonctionnent mieux lorsque les coéquipiers peuvent opérer indépendamment. Pour les tâches séquentielles, les modifications du même fichier ou le travail avec de nombreuses dépendances, une seule session ou les subagents sont plus efficaces.

Comparer avec les subagents

Les équipes d'agents et les subagents vous permettent tous deux de paralléliser le travail, mais ils fonctionnent différemment. Pour les sessions séparées qui se transmettent des messages les unes aux autres sans équipe, consultez la messagerie inter-sessions.

Utilisez les subagents lorsque vous avez besoin de travailleurs rapides et ciblés qui rendent compte. Utilisez les équipes d'agents lorsque les coéquipiers doivent partager les conclusions, se contester mutuellement et se coordonner de manière autonome.

Activer les équipes d'agents

Les équipes d'agents sont désactivées par défaut. Activez-les en définissant la variable d'environnement CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS sur 1, soit dans votre environnement shell, soit via settings.json :

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

L'activation des équipes d'agents modifie également la délégation ordinaire. Claude peut nommer un sous-agent de sa propre initiative, et tant que les équipes d'agents sont activées, un sous-agent que Claude nomme se lance en tant que coéquipier, de sorte que les équipes peuvent se former même si vous n'en aviez pas demandé une. Pour plus d'informations, consultez Comment Claude démarre les équipes d'agents ; pour désactiver ce comportement, consultez Claude crée des coéquipiers au lieu de sous-agents.

La création de coéquipiers nécessite également une session interactive. En mode non-interactif avec l'indicateur -p, y compris les sessions Agent SDK, Claude ne crée pas de coéquipiers, et un sous-agent que Claude nomme s'exécute en tant que sous-agent ordinaire même avec les équipes d'agents activées.

Démarrer votre première équipe d'agents

Après avoir activé les équipes d'agents, décrivez la tâche et les coéquipiers que vous souhaitez en langage naturel. Claude les crée et coordonne le travail en fonction de votre prompt.

Cet exemple fonctionne bien car les trois rôles sont indépendants et peuvent explorer le problème sans attendre les uns les autres :

Je conçois un outil CLI qui aide les développeurs à suivre les commentaires TODO dans
leur base de code. Créez trois coéquipiers pour explorer cela sous différents angles :
un sur l'UX, un sur l'architecture technique, un jouant l'avocat du diable.

À partir de là, Claude remplit une liste de tâches partagée dans une session qui dispose des outils Task, crée des coéquipiers pour chaque perspective, les fait explorer le problème, et synthétise les conclusions une fois terminé.

Claude peut parfois utiliser des sous-agents au lieu de créer une équipe. Les sous-agents apparaissent dans le même panneau d'agents que les coéquipiers, donc le panneau seul ne confirme pas qu'une équipe s'est formée. Si Claude a créé des sous-agents à la place, demandez à nouveau et demandez explicitement une équipe d'agents.

Le terminal du chef liste les coéquipiers dans le panneau d'agents en dessous de l'entrée du prompt. À partir du panneau :

• Flèches haut et bas : sélectionner un coéquipier
• Entrée : ouvrir la transcription du coéquipier sélectionné et lui envoyer un message directement
• Échap : effacer la sélection. Pendant que vous consultez la transcription d'un coéquipier, Échap interrompt le tour actuel de ce coéquipier

À partir de la v2.1.199, la ligne d'un coéquipier inactif reste dans le panneau tant que n'importe quel coéquipier ou sous-agent travaille encore, vous pouvez donc la sélectionner pour examiner sa transcription ou lui envoyer plus de travail. Une fois que chaque agent du panneau est inactif, les lignes inactives se masquent après 30 secondes et réapparaissent au prochain tour du coéquipier ; le coéquipier continue de fonctionner et reste adressable pendant qu'il est masqué. Dans les versions v2.1.181 à v2.1.198, une ligne inactif s'est masquée 30 secondes après la fin de son propre tour, même si d'autres coéquipiers travaillaient encore ; les lignes inactives ne sont pas masquées dans les versions antérieures à v2.1.181.

Lorsque plus de trois coéquipiers sont inactifs à la fois, les lignes au-delà des trois premières se réduisent en une seule ligne qui compte les coéquipiers réduits, comme 2 agents inactifs quand cinq sont inactifs. Sélectionnez-la et appuyez sur Entrée pour développer les lignes réduites, ou appuyez sur Échap pour les réduire à nouveau. Les coéquipiers qui travaillent, les coéquipiers qui ont échoué, et le coéquipier que vous consultez conservent toujours leurs propres lignes.

Si vous souhaitez que chaque coéquipier soit dans son propre volet divisé, consultez Choisir un mode d'affichage.

Contrôler votre équipe d'agents

Dites au chef ce que vous voulez en langage naturel. Il gère la coordination d'équipe, l'assignation de tâches et la délégation en fonction de vos instructions.

Choisir un mode d'affichage

Les équipes d'agents supportent deux modes d'affichage :

• In-process : tous les coéquipiers s'exécutent dans votre terminal principal. Utilisez les touches fléchées haut et bas dans le panneau d'agent pour sélectionner un coéquipier, puis appuyez sur Entrée pour l'afficher et tapez pour lui envoyer un message directement. Fonctionne dans n'importe quel terminal, aucune configuration supplémentaire requise.
• Volets divisés : chaque coéquipier obtient son propre volet. Vous pouvez voir la sortie de tout le monde à la fois et cliquer dans un volet pour interagir directement. Nécessite tmux ou iTerm2.

La valeur par défaut est "in-process". Définissez "auto" pour activer les volets divisés lorsque vous êtes déjà en train de s'exécuter dans une session tmux, ou lorsque votre terminal est iTerm2 avec le CLI it2 installé, en revenant à in-process sinon. Le paramètre "tmux" active le mode volets divisés et détecte automatiquement s'il faut utiliser tmux ou iTerm2 en fonction de votre terminal.

À partir de la v2.1.186, définissez "iterm2" pour utiliser explicitement les volets divisés natifs d'iTerm2. Ce mode nécessite le CLI it2 et affiche une erreur avec la commande d'installation si it2 est manquant. L'invite de configuration qui propose d'installer it2 ou de basculer vers tmux apparaît sous "auto" ou "tmux" lorsque votre terminal est iTerm2 et que tmux est disponible comme solution de secours.

Pour remplacer la valeur par défaut, définissez teammateMode dans ~/.claude/settings.json :

{
  "teammateMode": "auto"
}

Pour définir le mode pour une seule session, passez-le en tant que drapeau :

claude --teammate-mode auto

Le drapeau --teammate-mode est expérimental et n'apparaît pas dans claude --help.

Le mode volets divisés nécessite soit tmux soit iTerm2 avec le CLI it2. Pour installer manuellement :

• tmux : installez via le gestionnaire de paquets de votre système. Consultez le wiki tmux pour les instructions spécifiques à la plateforme.
• iTerm2 : installez le CLI it2, puis activez l'API Python dans iTerm2 → Paramètres → Général → Magie → Activer l'API Python.

Spécifier les coéquipiers et les modèles

Claude décide du nombre de coéquipiers à générer en fonction de votre tâche, ou vous pouvez spécifier exactement ce que vous voulez :

Générez 4 coéquipiers pour refactoriser ces modules en parallèle. Utilisez Sonnet pour
chaque coéquipier.

Claude Code choisit le modèle de chaque coéquipier parmi le premier de ceux-ci qui s'applique :

1. Le modèle que votre invite de génération nomme pour ce coéquipier.
2. Pour un coéquipier généré à partir d'une définition de sous-agent, le model de la définition, où inherit sélectionne le modèle du chef.
3. CLAUDE_CODE_SUBAGENT_MODEL, lorsqu'il est défini sur autre chose que inherit.
4. Le modèle actuel du chef.

Si vous définissez CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, les deux premières sources ne s'appliquent pas. Claude Code choisit le modèle de chaque coéquipier à partir de CLAUDE_CODE_SUBAGENT_MODEL lorsqu'il est défini sur autre chose que inherit, et à partir du modèle actuel du chef sinon. Nécessite Claude Code v2.1.257 ou ultérieur.

Avant la v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL venait en premier dans cet ordre.

Claude Code vérifie le modèle qu'il sélectionne pour un coéquipier par rapport à la liste d'autorisation availableModels de votre organisation. Lorsque la liste d'autorisation bloque une valeur, Claude Code substitue un autre modèle :

• Alias de famille tel que opus : sur l'API Anthropic et Claude Platform sur AWS, Claude Code exécute le coéquipier sur la version la plus récente de cette famille que la liste d'autorisation permet. Sur les fournisseurs avec des ID de modèle spécifiques au fournisseur, où la substitution ne fonctionne pas, un alias bloqué revient comme toute autre valeur bloquée selon la puce suivante
• Toute autre valeur bloquée, y compris un alias de famille sur les fournisseurs où la substitution ne fonctionne pas, ou un alias dont la famille n'a pas de version autorisée : Claude Code exécute le coéquipier sur le modèle du chef à la place. Si vous définissez CLAUDE_CODE_SUBAGENT_MODEL, Claude Code essaie d'abord ce modèle, selon ces mêmes règles

Les coéquipiers héritent du niveau d'effort du chef. En mode volets divisés, cela s'applique à partir de la v2.1.186 ; les versions antérieures ne transmettaient pas l'effort de session du chef aux coéquipiers en mode volets divisés.

Exiger que les coéquipiers planifient avant de mettre en œuvre

Pour les tâches complexes ou risquées, vous pouvez exiger que les coéquipiers planifient avant de mettre en œuvre. Un coéquipier que Claude génère tandis que le chef est en mode plan fonctionne en mode plan en lecture seule jusqu'à ce que son plan soit prêt. Basculez d'abord le chef en mode plan, puis demandez le coéquipier :

Générez un coéquipier architecte pour refactoriser le module d'authentification.

Lorsqu'un coéquipier termine la planification, il envoie une demande d'approbation du plan au chef. Claude Code approuve le plan dans la session du chef dès que la demande arrive, sans que le chef l'examine. Les modifications et commandes du coéquipier passent toujours par les invites de permission décrites dans Permissions. Une fois approuvé, le coéquipier quitte le mode plan et commence la mise en œuvre.

Parler directement aux coéquipiers

Chaque coéquipier est une session Claude Code complète et indépendante. Vous pouvez envoyer un message à n'importe quel coéquipier directement pour donner des instructions supplémentaires, poser des questions de suivi ou rediriger son approche.

• Mode in-process : utilisez les touches fléchées haut et bas dans le panneau d'agent pour sélectionner un coéquipier, puis appuyez sur Entrée pour afficher sa session et tapez pour lui envoyer un message. Appuyez sur x sur un coéquipier sélectionné pour l'arrêter. Appuyez sur Ctrl+T pour basculer la liste des tâches.
• Mode volets divisés : cliquez dans le volet d'un coéquipier pour interagir directement avec sa session. Chaque coéquipier a une vue complète de son propre terminal.

Pendant que vous visualisez un coéquipier in-process, le texte brut et les skills vont à ce coéquipier, mais les commandes intégrées s'exécutent toujours dans la session du chef.

Le modèle et le mode rapide d'un coéquipier sont fixés lorsqu'il est généré, donc /model et /fast ne changent que les paramètres du chef. À partir de la v2.1.199, taper l'une ou l'autre commande en visualisant un coéquipier affiche un avis indiquant que le changement s'applique au chef ; les versions antérieures l'appliquaient au chef sans indication. /effort s'applique toujours aux tours ultérieurs du coéquipier visualisé, car les coéquipiers suivent le niveau d'effort du chef.

Assigner et revendiquer des tâches

La liste de tâches partagée coordonne le travail dans l'équipe. Le chef crée des tâches et les coéquipiers les accomplissent. Les tâches ont trois états : en attente, en cours et terminées. Les tâches peuvent également dépendre d'autres tâches : une tâche en attente avec des dépendances non résolues ne peut pas être revendiquée jusqu'à ce que ces dépendances soient complétées.

Les agents sans les outils Task se coordonnent par des messages à la place de la liste de tâches partagée.

Le chef peut assigner des tâches explicitement, ou les coéquipiers peuvent les revendiquer eux-mêmes :

• Le chef assigne : dites au chef quelle tâche donner à quel coéquipier
• Auto-revendication : après avoir terminé une tâche, un coéquipier choisit la prochaine tâche non assignée et non bloquée de sa propre initiative

La revendication de tâche utilise le verrouillage de fichiers pour prévenir les conditions de course lorsque plusieurs coéquipiers tentent de revendiquer la même tâche simultanément.

Arrêter les coéquipiers

Pour terminer gracieusement la session d'un coéquipier, référencez-le par son nom. Par exemple, avec un coéquipier nommé chercheur :

Demandez au coéquipier chercheur d'arrêter

Le chef envoie une demande d'arrêt. Le coéquipier peut approuver, quittant gracieusement, ou rejeter avec une explication.

Les répertoires partagés de l'équipe sont nettoyés automatiquement lorsque la session se termine, il n'y a donc pas d'étape de nettoyage séparé. Consultez Architecture pour voir quels répertoires sont supprimés et lesquels persistent pour les sessions reprises.

Appliquer des portes de qualité avec des hooks

Utilisez les hooks pour appliquer des règles lorsque les coéquipiers terminent le travail ou que les tâches sont créées ou complétées :

• TeammateIdle : s'exécute lorsqu'un coéquipier est sur le point de devenir inactif. Quittez avec le code 2 pour envoyer des commentaires et garder le coéquipier au travail.
• TaskCreated : s'exécute lorsqu'une tâche est en cours de création. Quittez avec le code 2 pour empêcher la création et envoyer des commentaires.
• TaskCompleted : s'exécute lorsqu'une tâche est marquée comme complète. Quittez avec le code 2 pour empêcher la complétion et envoyer des commentaires.

Comment fonctionnent les équipes d'agents

Cette section couvre l'architecture et la mécanique derrière les équipes d'agents. Si vous souhaitez commencer à les utiliser, consultez Contrôler votre équipe d'agents ci-dessus.

Comment Claude démarre les équipes d'agents

Pour démarrer une équipe, demandez à Claude des coéquipiers. Claude lance un coéquipier lorsqu'il appelle l'outil Agent avec un name tandis que les équipes d'agents sont activées, sauf si l'appel est un fork ou passe isolation sur l'appel lui-même. Claude Code ne vous demande pas de confirmer le lancement.

Claude nomme également les subagents ordinaires de lui-même afin de pouvoir les contacter ultérieurement. Ces appels suivent la même règle, de sorte que les équipes peuvent se former même si vous n'en aviez pas demandé une. Si vous préférez les subagents, désactivez les équipes d'agents.

Architecture

Une équipe d'agents se compose de :

La boîte aux lettres de chaque agent est un fichier JSON à ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Claude Code valide chaque entrée lorsqu'il lit un fichier de boîte aux lettres. Les entrées qui ne correspondent pas au format de message sont signalées comme des erreurs et supprimées du fichier ; les messages valides sont toujours livrés. Avant la v2.1.207, une seule entrée de boîte aux lettres malformée causait une erreur répétée chaque seconde et bloquait la livraison pour cette boîte aux lettres jusqu'à ce que vous supprimiez le fichier manuellement.

Claude Code signale un message comme envoyé uniquement lorsque l'écriture dans le fichier de boîte aux lettres du destinataire réussit, que le message soit du texte brut ou un message de protocole structuré tel qu'une approbation de plan ou une demande d'arrêt. Lorsque l'écriture échoue, par exemple parce que le disque est plein ou que le répertoire de boîte aux lettres n'est pas accessible en écriture, l'agent émetteur reçoit une erreur et rien n'est envoyé. Consultez Impossible d'écrire dans la boîte de réception d'un coéquipier pour les messages d'erreur et les étapes de récupération.

Claude Code gère automatiquement les dépendances de tâches : lorsqu'un coéquipier complète une tâche dont d'autres tâches dépendent, il déverrouille les tâches dépendantes sans aucune action de votre part.

Les équipes et les tâches sont stockées localement sous un nom dérivé de la session. Le nom est session- suivi des huit premiers caractères de l'ID de session :

• Configuration d'équipe : ~/.claude/teams/{team-name}/config.json
• Liste de tâches : ~/.claude/tasks/{team-name}/

Claude Code génère automatiquement ces deux éléments au démarrage de la session et les met à jour à mesure que les coéquipiers rejoignent, deviennent inactifs ou partent. Le répertoire de configuration d'équipe est supprimé lorsque la session se termine. Le répertoire de liste de tâches persiste localement et n'est jamais téléchargé, donc les sessions reprises conservent leurs tâches. La rétention est régie par le même cleanupPeriodDays que vous contrôlez déjà pour les transcriptions de session, en suivant les règles de nettoyage de rétention.

La configuration d'équipe contient l'état d'exécution tel que les ID de session et les ID de volet tmux, donc ne l'éditez pas à la main ou ne la pré-créez pas : vos modifications sont écrasées lors de la prochaine mise à jour d'état.

Pour définir des rôles de coéquipiers réutilisables, utilisez plutôt les définitions de subagents.

La configuration d'équipe contient un tableau members avec le nom et l'ID d'agent de chaque coéquipier. L'entrée du chef porte toujours le type d'agent team-lead. L'entrée d'un coéquipier porte le type d'agent que le chef a nommé lors de son lancement, qu'il s'agisse d'un type intégré ou d'une définition de subagent, et omet le champ lorsque le chef n'en a nommé aucun. Les coéquipiers peuvent lire ce fichier pour découvrir les autres membres de l'équipe.

Il n'y a pas d'équivalent au niveau du projet de la configuration d'équipe. Un fichier comme .claude/teams/teams.json dans votre répertoire de projet n'est pas reconnu comme configuration ; Claude le traite comme un fichier ordinaire.

Utiliser les définitions de subagents pour les coéquipiers

Lors de la génération d'un coéquipier dans l'un ou l'autre mode d'affichage, vous pouvez référencer un type de subagent du projet, de l'utilisateur ou de la portée de subagent gérée. Cela vous permet de définir un rôle une fois, comme un examinateur de sécurité ou un exécuteur de tests, et de le réutiliser à la fois comme subagent délégué et comme coéquipier d'équipe d'agents.

Pour utiliser une définition de subagent, nommez-la lorsque vous demandez à Claude de lancer le coéquipier :

Lancez un coéquipier utilisant le type d'agent security-reviewer pour auditer le module d'authentification.

Claude Code lit la définition de subagent que vous avez nommée et applique ces parties à ce coéquipier. Lorsqu'une partie dépend du mode d'affichage du coéquipier, l'entrée le précise :

• tools : Claude Code limite le coéquipier aux outils de la liste tools de la définition. Pour un coéquipier en processus, Claude Code ajoute SendMessage à cette liste, et dans une session qui dispose des outils Task il ajoute également TaskCreate, TaskGet, TaskList et TaskUpdate.
• model : Claude Code utilise le model de la définition dans l'un ou l'autre mode d'affichage lorsque votre prompt de lancement n'en nomme pas un. Consultez comment Claude Code choisit le modèle d'un coéquipier.
• Body : pour un coéquipier en processus, Claude Code ajoute le body de la définition à son prompt système par défaut en tant qu'instructions supplémentaires. Pour un coéquipier en volet divisé, Claude Code utilise le body à la place de son prompt système par défaut.
• skills : Claude Code n'applique pas les skills de la définition à un coéquipier dans l'un ou l'autre mode d'affichage. Le coéquipier charge les skills à partir de vos paramètres de projet et d'utilisateur.
• mcpServers : pour un coéquipier en volet divisé, Claude Code applique les mcpServers de la définition selon les règles pour ce champ, qui couvrent également une session démarrée avec --agent. Un coéquipier en processus ignore le champ et charge les serveurs MCP à partir de vos paramètres de projet et d'utilisateur.

Lorsque Claude envoie un message à un coéquipier en processus qui n'est plus en cours d'exécution, Claude Code le relance dans la même session, restaure toute conversation enregistrée pour lui, et lui donne le message comme son prochain prompt. Après avoir repris une session, les coéquipiers ne sont pas relancés de cette manière, selon la limitation de reprise.

Pour un coéquipier qu'il relance, Claude Code réapplique une définition qui provient du répertoire .claude/agents/ d'un projet ou d'un répertoire --add-dir uniquement si vous avez approuvé le dossier dans lequel se trouve le fichier d'agent. Approuver un dossier parent ne compte pas. Jusqu'à ce moment, le coéquipier revient sans aucun des outils ou instructions de la définition, en conservant uniquement les outils que Claude Code ajoute à chaque coéquipier en processus. Consultez la définition d'agent du coéquipier n'a pas été restaurée pour le texte de la notification.

Permissions

Les coéquipiers commencent avec le mode de permission du chef, sauf le mode dontAsk, qu'ils n'héritent pas. Si le chef s'exécute avec --dangerously-skip-permissions, tous les coéquipiers le font aussi. Après la génération, vous pouvez modifier le mode de permission d'un coéquipier individuel, mais vous ne pouvez pas définir les modes de permission par coéquipier au moment de la génération.

Les invites de permission des coéquipiers remontent à la session chef, donc approuvez-les vous-même là-bas. L'approbation du plan est l'exception conçue : la session chef accorde les approbations de plan des coéquipiers sans une invite séparée pour vous.

Messages entre agents

Lorsqu'un agent envoie un message à un autre via SendMessage, Claude Code indique à l'agent destinataire que le message provient d'une autre session Claude, et non de vous. Un coéquipier ne peut pas approuver une invite de permission ou fournir un consentement en votre nom, et un coéquipier auquel une action a été refusée ne peut pas la relayer à un autre coéquipier pour contourner la vérification. Les mêmes règles s'appliquent à un message qui arrive de l'une de vos autres sessions Claude Code, en dehors de l'équipe entièrement.

En mode automatique, le classificateur applique deux vérifications aux messages entre agents :

• Il traite une approbation relayée par un autre agent comme une entrée non fiable plutôt que comme une confirmation de votre part.
• Il examine chaque message avant que Claude Code ne le livre, qu'il s'agisse d'un message brut ou d'un message de protocole structuré tel qu'une demande d'arrêt ou une réponse d'approbation de plan. Un message qu'il bloque n'atteint jamais le destinataire.

Contexte et communication

Chaque coéquipier a sa propre fenêtre de contexte. Lorsqu'il est généré, un coéquipier charge le même contexte de projet qu'une session régulière : CLAUDE.md, serveurs MCP et skills. Il reçoit également le prompt de génération du chef. L'historique de conversation du chef ne se transporte pas.

Comment les coéquipiers partagent les informations :

• Livraison automatique de messages : lorsque les coéquipiers envoient des messages, ils sont livrés automatiquement aux destinataires. Le chef n'a pas besoin d'interroger les mises à jour.
• Notifications d'inactivité : lorsqu'un coéquipier termine et s'arrête, il notifie automatiquement le chef et inclut sa réponse finale dans la notification. Un coéquipier dont le tour se termine sur une erreur API notifie le chef qu'il a échoué et inclut le texte d'erreur.
• Liste de tâches partagée : les agents qui disposent des outils Task peuvent voir l'état des tâches et revendiquer le travail disponible.
• Messagerie des coéquipiers : envoyer un message à un coéquipier spécifique par son nom. Pour atteindre tout le monde, envoyez un message par destinataire.

Le chef assigne à chaque coéquipier un nom lorsqu'il le génère, et n'importe quel coéquipier peut envoyer un message à n'importe quel autre par ce nom. Pour obtenir des noms prévisibles que vous pouvez référencer dans les prompts ultérieurs, dites au chef comment appeler chaque coéquipier dans votre instruction de génération.

Utilisation des tokens

Les équipes d'agents utilisent considérablement plus de tokens qu'une seule session. Chaque coéquipier a sa propre fenêtre de contexte, et l'utilisation des tokens augmente avec le nombre de coéquipiers actifs. Pour la recherche, l'examen et le travail sur les nouvelles fonctionnalités, les tokens supplémentaires en valent généralement la peine. Pour les tâches de routine, une seule session est plus rentable. Consultez les coûts des tokens des équipes d'agents pour les conseils d'utilisation.

Un coéquipier en processus dont les demandes sortent du bucket TTL du cache de la conversation principale, donc son cache dure cinq minutes par défaut, y compris sur un abonnement Claude. Pour le conserver pendant une heure, définissez subagentPromptCacheTtl sur 1h. L'API facture les écritures de cache d'une heure à un taux plus élevé.

Exemples de cas d'usage

Ces exemples montrent comment les équipes d'agents gèrent les tâches où l'exploration parallèle ajoute de la valeur.

Exécuter un examen de code parallèle

Un seul examinateur tend à graviter vers un type de problème à la fois. Diviser les critères d'examen en domaines indépendants signifie que la sécurité, l'impact sur les performances et la couverture de test reçoivent tous une attention approfondie simultanément. Le prompt assigne à chaque coéquipier une lentille distincte pour qu'ils ne se chevauchent pas :

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Chaque examinateur travaille à partir de la même PR mais applique un filtre différent. Le chef synthétise les conclusions de tous les trois après qu'ils aient terminé.

Enquêter avec des hypothèses concurrentes

Lorsque la cause première est peu claire, un seul agent tend à trouver une explication plausible et s'arrête. Le prompt combat cela en rendant les coéquipiers explicitement adversaires : le travail de chacun n'est pas seulement d'enquêter sur sa propre théorie mais de contester les autres.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

La structure du débat est le mécanisme clé ici. L'enquête séquentielle souffre de l'ancrage : une fois qu'une théorie est explorée, l'enquête ultérieure est biaisée vers elle.

Avec plusieurs enquêteurs indépendants essayant activement de réfuter les uns les autres, la théorie qui survit est beaucoup plus susceptible d'être la cause première réelle.

Meilleures pratiques

Donner aux coéquipiers suffisamment de contexte

Les coéquipiers chargent automatiquement le contexte du projet, y compris CLAUDE.md, serveurs MCP et skills, mais ils n'héritent pas de l'historique de conversation du chef. Consultez Contexte et communication pour les détails. Incluez les détails spécifiques à la tâche dans le prompt de génération :

Générez un coéquipier examinateur de sécurité avec le prompt : « Examinez le module d'authentification
à src/auth/ pour les vulnérabilités de sécurité. Concentrez-vous sur la gestion des tokens, la gestion
des sessions et la validation des entrées. L'application utilise des tokens JWT stockés dans
des cookies httpOnly. Signalez tout problème avec les évaluations de gravité. »

Choisir une taille d'équipe appropriée

Il n'y a pas de limite stricte au nombre de coéquipiers, mais des contraintes pratiques s'appliquent :

• Les coûts des tokens augmentent linéairement : chaque coéquipier a sa propre fenêtre de contexte et consomme des tokens indépendamment. Consultez les coûts des tokens des équipes d'agents pour les détails.
• La surcharge de coordination augmente : plus de coéquipiers signifie plus de communication, de coordination de tâches et de risques de conflits
• Rendements décroissants : au-delà d'un certain point, les coéquipiers supplémentaires n'accélèrent pas le travail proportionnellement

Commencez avec 3 à 5 coéquipiers pour la plupart des flux de travail. Cela équilibre le travail parallèle avec une coordination gérable. Si vous avez 15 tâches indépendantes, 3 coéquipiers est un bon point de départ.

Augmentez l'échelle uniquement lorsque le travail bénéficie véritablement d'avoir des coéquipiers travaillant simultanément. Trois coéquipiers ciblés surpassent souvent cinq dispersés.

Dimensionner les tâches de manière appropriée

• Trop petites : la surcharge de coordination dépasse le bénéfice
• Trop grandes : les coéquipiers travaillent trop longtemps sans points de contrôle, augmentant le risque d'effort gaspillé
• Juste bien : des unités autonomes qui produisent un livrable clair, comme une fonction, un fichier de test ou un examen

Attendre que les coéquipiers terminent

Parfois, le chef commence à mettre en œuvre des tâches lui-même au lieu d'attendre les coéquipiers. Si vous remarquez cela :

Attendez que vos coéquipiers complètent leurs tâches avant de procéder

Commencer par la recherche et l'examen

Si vous êtes nouveau aux équipes d'agents, commencez par des tâches qui ont des limites claires et ne nécessitent pas d'écrire du code : examiner une PR, rechercher une bibliothèque ou enquêter sur un bug. Ces tâches montrent la valeur de l'exploration parallèle sans les défis de coordination qui accompagnent la mise en œuvre parallèle.

Éviter les conflits de fichiers

Deux coéquipiers éditant le même fichier entraîne des écrasements. Divisez le travail pour que chaque coéquipier possède un ensemble de fichiers différent.

Surveiller et diriger

Vérifiez la progression des coéquipiers, redirigez les approches qui ne fonctionnent pas et synthétisez les conclusions au fur et à mesure qu'elles arrivent. Laisser une équipe s'exécuter sans surveillance pendant trop longtemps augmente le risque d'effort gaspillé.

Dépannage

Les coéquipiers n'apparaissent pas

Si les coéquipiers n'apparaissent pas après avoir demandé à Claude de créer une équipe :

• En mode in-process, les coéquipiers apparaissent dans le panneau d'agent sous l'entrée de prompt. Utilisez les touches fléchées haut et bas pour en sélectionner un, puis appuyez sur Entrée pour l'afficher.
• Une ligne de coéquipier qui a disparu après être restée inactive a été masquée, non arrêtée. Les lignes inactives se masquent 30 secondes après que le panneau entier devienne inactif et réapparaissent au prochain tour du coéquipier. Quand plus de trois coéquipiers sont inactifs, leurs lignes excédentaires s'effondrent en une seule ligne N idle agents que Entrée développe. Envoyez un message au coéquipier par son nom pour ramener une ligne masquée.
• Vérifiez que la tâche que vous avez donnée à Claude était suffisamment complexe pour justifier une équipe. Claude décide s'il faut générer des coéquipiers en fonction de la tâche.
• Si vous avez explicitement demandé des volets divisés, assurez-vous que tmux est installé et disponible dans votre PATH :

  which tmux
  

• Pour iTerm2, vérifiez que le CLI it2 est installé et que l'API Python est activée dans les préférences d'iTerm2.

Claude crée des coéquipiers au lieu de sous-agents

Tandis que les équipes d'agents sont activées, un sous-agent que Claude nomme dans la session du chef se lance en tant que coéquipier. Claude peut nommer des sous-agents de sa propre initiative, donc cela peut se produire lors d'une délégation que vous n'aviez jamais encadrée comme du travail d'équipe.

Pour que les sous-agents nommés se lancent à nouveau en tant que sous-agents, désactivez les équipes d'agents en définissant CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS à 0 :

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

Vous n'avez pas besoin de démarrer une nouvelle session : Claude Code réapplique les valeurs env du fichier de paramètres à la session en cours lorsque vous enregistrez, et relit la variable chaque fois que Claude crée un sous-agent, donc le prochain sous-agent que Claude nomme se lance en tant que sous-agent.

Définir la variable à 0 dans votre settings.json utilisateur remplace une exportation de shell. D'autres sources de paramètres peuvent toujours activer les équipes d'agents :

• Fichiers de paramètres de priorité supérieure : les paramètres de projet, les paramètres locaux et une charge utile --settings s'appliquent après les paramètres utilisateur, donc une entrée env qui définit la variable à 1 dans l'un d'eux gagne. Voir Priorité des paramètres.
• Paramètres gérés : les paramètres gérés s'appliquent après toute autre source. Si votre organisation active les équipes d'agents là-bas, demandez à votre administrateur de modifier la valeur gérée.

Après la modification, Claude peut toujours nommer des sous-agents, et le nom continue de fonctionner comme une adresse SendMessage. Claude reçoit le résultat de chaque sous-agent lorsqu'il se termine.

Trop de demandes de permission

Les demandes de permission des coéquipiers remontent au chef, ce qui peut créer des frictions. Pré-approuvez les opérations courantes dans vos paramètres de permission avant de générer les coéquipiers pour réduire les interruptions.

Les agents s'arrêtent prématurément

Les coéquipiers peuvent s'arrêter après avoir rencontré des erreurs au lieu de se rétablir. Vérifiez leur sortie en sélectionnant le coéquipier dans le panneau d'agent et en appuyant sur Entrée en mode in-process, ou en cliquant sur le volet en mode divisé, puis :

• Donnez-leur des instructions supplémentaires directement
• Générez un coéquipier de remplacement pour continuer le travail

Un message du chef ou d'un autre coéquipier réveille un coéquipier in-process qui attend de réessayer une demande API échouée, il réessaie donc immédiatement au lieu d'attendre le délai de réessai complet.

Le chef peut aussi s'arrêter prématurément, décidant que l'équipe est terminée avant que toutes les tâches ne soient réellement complètes. Si cela se produit, dites-lui de continuer.

Sessions tmux orphelines

Si une session tmux persiste après la fin de l'équipe, elle peut ne pas avoir été complètement nettoyée. Listez les sessions et tuez celle créée par l'équipe :

tmux ls
tmux kill-session -t <session-name>

Limitations

Les équipes d'agents sont expérimentales. Les limitations actuelles à connaître :

• Pas de reprise de session avec les coéquipiers in-process : /resume et /rewind ne restaurent pas les coéquipiers in-process. Après la reprise d'une session, le chef peut tenter d'envoyer un message aux coéquipiers qui n'existent plus. Si cela se produit, dites au chef de générer de nouveaux coéquipiers.
• L'état des tâches peut être en retard : les coéquipiers échouent parfois à marquer les tâches comme complètes, ce qui bloque les tâches dépendantes. Si une tâche semble bloquée, vérifiez si le travail est réellement terminé et mettez à jour l'état de la tâche manuellement ou dites au chef de pousser le coéquipier.
• L'arrêt peut être lent : les coéquipiers terminent leur demande actuelle ou appel d'outil avant de s'arrêter, ce qui peut prendre du temps.
• Une équipe par session : une session a exactement une équipe, limitée à cette session. Vous ne pouvez pas créer d'équipes nommées supplémentaires ou partager une équipe entre les sessions.
• Pas d'équipes imbriquées : les coéquipiers ne peuvent pas générer leurs propres coéquipiers. Seul le chef peut gérer l'équipe.
• Pas de sous-agents d'arrière-plan à partir de coéquipiers in-process : les propres sous-agents d'un coéquipier in-process s'exécutent au premier plan, car le travail d'arrière-plan d'un coéquipier ne peut pas survivre au processus du chef. Claude Code retourne une erreur quand un coéquipier génère un sous-agent dont la définition définit background: true. Une demande run_in_background: true d'un coéquipier échoue également, soit avec une erreur, soit en s'exécutant silencieusement au premier plan, comme décrit dans comment Claude Code choisit le premier plan ou l'arrière-plan. Les sous-agents lancés à partir de la conversation principale suivent la valeur par défaut d'arrière-plan.
• Le chef est fixe : la session principale est le chef pour sa durée de vie. Vous ne pouvez pas promouvoir un coéquipier en chef ou transférer le leadership.
• Permissions définies au moment de la génération : les coéquipiers commencent avec le mode de permission décrit sous Permissions. Vous pouvez modifier le mode de permission d'un coéquipier individuel après la génération, mais vous ne pouvez pas définir les modes de permission par coéquipier au moment de la génération.
• Les volets divisés nécessitent tmux ou iTerm2 : le mode in-process par défaut fonctionne dans n'importe quel terminal. Le mode volets divisés n'est pas supporté dans le terminal intégré de VS Code, Windows Terminal ou Ghostty.

Prochaines étapes

Explorez les approches connexes pour le travail parallèle et la délégation :

• Délégation légère : les subagents génèrent des agents auxiliaires pour la recherche ou la vérification au sein de votre session, mieux pour les tâches qui n'ont pas besoin de coordination inter-agents
• Messagerie entre vos propres sessions : la messagerie inter-sessions permet à Claude de transmettre les résultats entre les sessions que vous exécutez vous-même
• Sessions parallèles manuelles : les Git worktrees vous permettent d'exécuter plusieurs sessions Claude Code vous-même sans coordination d'équipe automatisée