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.

[!WARNING]

Les équipes d'agents sont expérimentales et désactivées par défaut. Activez-les en définissant CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 dans votre settings.json ou environnement. Sans cette variable, aucune équipe n'est configurée au démarrage de la session, aucun répertoire d'équipe n'est écrit, et Claude ne crée pas ou ne propose pas de coéquipiers. Les équipes d'agents ont des limitations connues concernant la reprise de session, la coordination des tâches et le comportement d'arrêt.

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.

Les subagents rendent compte des résultats à l'agent principal. Dans les équipes d'agents, les coéquipiers partagent une liste de tâches, revendiquent du travail et communiquent directement les uns avec les autres.

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 en langage naturel la tâche et les coéquipiers que vous souhaitez. 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 s'attendre les uns les autres :

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

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

Il peut arriver que Claude utilise 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 ; le panneau seul ne confirme donc pas qu'une équipe a été formée. Si Claude a créé des sous-agents à la place, redemandez-lui en sollicitant explicitement une équipe d'agents.

Le terminal du responsable affiche la liste des coéquipiers dans le panneau d'agents, sous la zone de saisie du prompt. Depuis le panneau :

• Flèches haut et bas : sélectionner un coéquipier
• Enter : ouvrir la transcription du coéquipier sélectionné et lui envoyer un message directement
• Escape : effacer la sélection. Lorsque vous consultez la transcription d'un coéquipier, Escape interrompt le tour en cours de ce coéquipier

La ligne d'un coéquipier inactif reste dans le panneau tant qu'un coéquipier ou un sous-agent est encore en train de travailler, ce qui vous permet de la sélectionner pour consulter sa transcription ou lui confier du travail supplémentaire. Une fois que tous les agents du panneau sont inactifs, les lignes inactives sont masquées au bout de 30 secondes et réapparaissent au tour suivant du coéquipier ; le coéquipier continue de s'exécuter et reste joignable pendant qu'il est masqué.

Lorsque plus de trois coéquipiers sont inactifs en même temps, les lignes au-delà des trois premières sont regroupées en une seule ligne qui indique le nombre de coéquipiers regroupés, par exemple 2 idle agents lorsque cinq sont inactifs. Sélectionnez-la et appuyez sur Enter pour déplier les lignes regroupées, ou appuyez sur Esc pour les regrouper à nouveau. Les coéquipiers en train de travailler, les coéquipiers en échec et le coéquipier que vous consultez conservent toujours leur propre ligne.

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

Contrôler votre équipe d'agents

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

Choisir un mode d'affichage

Les équipes d'agents prennent en charge 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 des agents pour sélectionner un coéquipier, puis appuyez sur Enter pour l'afficher et tapez pour lui envoyer un message directement. Fonctionne dans n'importe quel terminal, sans configuration supplémentaire.
• Volets divisés : chaque coéquipier dispose de son propre volet. Vous pouvez voir la sortie de tous en même temps et cliquer dans un volet pour interagir directement. Nécessite tmux ou iTerm2.

[!NOTE]

tmux présente des limitations connues sur certains systèmes d'exploitation et fonctionne traditionnellement mieux sur macOS. L'utilisation de tmux -CC dans iTerm2 est le point d'entrée recommandé pour tmux.

La valeur par défaut est "in-process". Définissez "auto" pour activer les volets divisés lorsque vous exécutez déjà une session tmux, ou lorsque votre terminal est iTerm2 avec la CLI it2 installée, avec une solution de repli sur le mode in-process dans les autres cas. 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.

Définissez "iterm2" pour utiliser explicitement les volets divisés natifs d'iTerm2. Ce mode nécessite la CLI it2 et affiche une erreur avec la commande d'installation si it2 est absent. L'invite de configuration qui propose d'installer it2 ou de basculer sur tmux apparaît avec "auto" ou "tmux" lorsque votre terminal est iTerm2 et que tmux est disponible comme solution de repli.

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 sous forme de flag :

claude --teammate-mode auto

Le flag --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 la CLI it2. Pour une installation manuelle :

• tmux : installez-le via le gestionnaire de paquets de votre système. Consultez le wiki tmux pour les instructions propres à chaque plateforme.
• iTerm2 : installez la CLI it2, puis activez l'API Python dans iTerm2 → Settings → General → Magic → Enable Python API.

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

Claude décide du nombre de coéquipiers à lancer en fonction de votre tâche, ou vous pouvez préciser exactement ce que vous voulez :

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Claude Code choisit le modèle de chaque coéquipier à partir de la première de ces sources qui s'applique :

1. Le modèle que votre prompt de lancement indique pour ce coéquipier.
2. Pour un coéquipier lancé à partir d'une définition de sous-agent, le model de la définition, où inherit sélectionne le modèle du responsable.
3. CLAUDE_CODE_SUBAGENT_MODEL, lorsqu'elle est définie sur une valeur autre que inherit.
4. Le modèle actuel du responsable.

Si un mod installé définit un modèle dans son hook agent.spawn, Claude Code utilise ce modèle à la place de la première source.

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'elle est définie sur une valeur autre que inherit, et à partir du modèle actuel du responsable dans le cas contraire. Nécessite Claude Code v2.1.257 ou une version ultérieure.

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

[!NOTE]

teammateDefaultModel a été supprimé dans la v2.1.234 ; Claude Code ignore une valeur résiduelle. Indiquez plutôt le modèle dans votre prompt.

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 lui substitue un autre modèle :

• Alias de famille tel que opus : sur l'API Anthropic et Claude Platform on AWS, Claude Code exécute le coéquipier sur la version la plus récente de cette famille autorisée par la liste d'autorisation. Sur les fournisseurs utilisant des identifiants de modèle propres au fournisseur, où la substitution ne fonctionne pas, un alias bloqué bascule comme toute autre valeur bloquée, selon le point suivant
• 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 aucune version autorisée : Claude Code exécute plutôt le coéquipier sur le modèle du responsable. Si vous définissez CLAUDE_CODE_SUBAGENT_MODEL, Claude Code essaie d'abord ce modèle, selon ces mêmes règles

Par défaut, un coéquipier utilisant le modèle du responsable hérite du niveau d'effort du responsable. En mode volets divisés, cela s'applique à partir de la v2.1.186 ; les versions antérieures ne transmettaient pas le niveau d'effort de la session du responsable aux coéquipiers en volets divisés. Pour un coéquipier utilisant un autre modèle, consultez Niveau d'effort des sous-agents et des coéquipiers.

Faire planifier les coéquipiers avant l'implémentation

Pour les tâches complexes ou risquées, vous pouvez demander aux coéquipiers de planifier avant d'implémenter. Un coéquipier que Claude lance pendant que le responsable est en mode plan travaille également en mode plan jusqu'à ce que son plan soit prêt. Passez d'abord le responsable en mode plan, puis demandez le coéquipier :

Spawn an architect teammate to refactor the authentication module.

Lorsque ce coéquipier a terminé sa planification, il envoie une demande d'approbation du plan au responsable. Si vous n'avez pas modifié le mode de permission de ce coéquipier depuis son lancement, Claude Code approuve le plan dès l'arrivée de la demande, sans que le responsable l'examine. Une fois le plan approuvé, le coéquipier quitte le mode plan et commence l'implémentation. Claude Code lui transmet le mode de permission actuel du responsable, ou Manual si celui-ci est le mode plan.

Si vous placez un coéquipier in-process en cours d'exécution en mode plan en appuyant sur Shift+Tab pendant que vous consultez sa session, c'est le responsable qui examine le plan de cette exécution au lieu que Claude Code l'approuve. Il ne vous est pas demandé de l'approuver ; le responsable l'approuve ou le renvoie pour révision.

Parler directement aux coéquipiers

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

• Mode in-process : utilisez les touches fléchées haut et bas dans le panneau des agents pour sélectionner un coéquipier, puis appuyez sur Enter 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 afficher ou masquer 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 dispose d'une vue complète de son propre terminal.

Lorsque vous consultez un coéquipier in-process, le texte brut et les skills sont envoyés à ce coéquipier, et les commandes intégrées sont envoyées à la session du responsable, avec ces garde-fous :

• /compact, /clear et /rewind agissent sur la conversation du responsable, donc Claude Code vous demande de confirmer avant d'exécuter l'une d'elles depuis cette vue.
• /model et /fast définissent le modèle et le mode rapide du responsable, et non ceux du coéquipier, donc elles ne s'exécutent pas depuis cette vue. Un avis vous en indique la raison.

Le modèle et le mode rapide d'un coéquipier sont fixés lors de son lancement.

Attribuer et réclamer des tâches

La liste de tâches partagée coordonne le travail au sein de l'équipe. Le responsable crée des tâches et les coéquipiers les traitent. Les tâches ont trois états : en attente, en cours et terminée. Une tâche peut également dépendre d'autres tâches et apparaît comme bloquée dans la liste des tâches jusqu'à ce que celles-ci soient terminées. Les coéquipiers ne réclament pas d'eux-mêmes une tâche bloquée, mais vous ou le responsable pouvez tout de même l'attribuer.

Les agents sans les outils Task se coordonnent plutôt par messages qu'au moyen de la liste de tâches partagée.

Le responsable peut attribuer des tâches explicitement, ou les coéquipiers peuvent les réclamer eux-mêmes :

• Attribution par le responsable : indiquez au responsable quelle tâche confier à quel coéquipier
• Réclamation autonome : après avoir terminé une tâche, un coéquipier prend de lui-même la prochaine tâche non attribuée et non bloquée

La réclamation des tâches utilise le verrouillage de fichiers pour éviter les situations de concurrence lorsque plusieurs coéquipiers tentent de réclamer la même tâche simultanément.

Arrêter des coéquipiers

Pour mettre fin proprement à la session d'un coéquipier, désignez-le par son nom. Par exemple, avec un coéquipier nommé researcher :

Ask the researcher teammate to shut down

Le responsable envoie une demande d'arrêt. Le coéquipier peut l'approuver, en s'arrêtant proprement, ou la rejeter avec une explication.

Les répertoires partagés de l'équipe sont nettoyés automatiquement à la fin de la session, il n'y a donc pas d'étape de nettoyage distincte. Consultez Architecture pour savoir quels répertoires sont supprimés et lesquels restent sur le disque.

Appliquer des contrôles qualité avec des hooks

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

• TeammateIdle : s'exécute lorsqu'un coéquipier est sur le point de devenir inactif. Quittez avec le code 2 pour envoyer un retour et maintenir 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 un retour.
• TaskCompleted : s'exécute lorsqu'une tâche est en train d'être marquée comme terminée. Quittez avec le code 2 pour empêcher la finalisation et envoyer un retour.

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.

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. Claude Code supprime le répertoire de configuration d'équipe lorsque la session se termine.
• Liste de tâches : ~/.claude/tasks/{team-name}/. Ce répertoire reste sur le disque après la fin de la session. Pour modifier la durée pendant laquelle Claude Code le conserve, définissez cleanupPeriodDays.

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.

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 sous-agent de la portée de sous-agent projet, utilisateur, gérée ou plugin. 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 sous-agent 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 :

Spawn a teammate using the security-reviewer agent type to audit the auth module.

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.
• disallowedTools : pour un coéquipier en processus, Claude Code retire de l'ensemble d'outils du coéquipier les outils listés dans le disallowedTools de la définition. SendMessage et les outils Task qu'il ajoute restent disponibles même lorsque la liste les nomme.
• effort : pour un coéquipier en processus, Claude Code applique l'effort de la définition selon les règles d'effort du frontmatter.
• autoCompactWindow : pour un coéquipier en processus, Claude Code applique l'autoCompactWindow de la définition selon les règles de ce champ. Un coéquipier en volet divisé ignore le champ. Nécessite Claude Code v2.1.296 ou ultérieure.
• 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

Pour faire défiler le mode de permission d'un coéquipier en cours d'exécution, appuyez sur Shift+Tab, bien qu'un coéquipier en processus puisse plutôt s'exécuter dans le mode du chef. Pour un coéquipier en volet divisé, appuyez sur ces touches dans son volet. Pour un coéquipier en processus, appuyez sur ces touches pendant que vous consultez sa session, et le coéquipier vérifie son mode lorsqu'il commence son prochain tour.

[!NOTE]

Un coéquipier en processus qui n'est pas en mode plan s'exécute dans le mode du chef tant que le chef est en mode acceptEdits, auto ou bypassPermissions. Passer le coéquipier en mode Manual n'y change rien, même si sa barre d'état affiche Manual.

Pour qu'il demande avant de modifier des fichiers, appuyez sur Enter sur la ligne main dans le panneau des agents et passez également le chef en mode Manual. Le chef demande alors lui aussi, tout comme tout autre coéquipier en mode Manual.

Vous ne pouvez pas définir les modes de permission par coéquipier au moment de la génération. Un nouveau coéquipier démarre avec le mode du chef, y compris le mode bypassPermissions, qu'active --dangerously-skip-permissions. Si le chef est en mode dontAsk, le coéquipier démarre plutôt en mode Manual. Pour un coéquipier en volet divisé d'un chef en mode Manual ou dontAsk, cela nécessite Claude Code v2.1.317 ou ultérieure.

Un coéquipier en processus s'exécute sous les règles d'autorisation et de refus actives du chef, de sorte que --disallowedTools, --tools et --allowedTools s'appliquent tous à lui. Pour un coéquipier en volet divisé, vérifiez chaque flag :

• --disallowedTools et --tools : le coéquipier démarre avec les règles de refus de ligne de commande et la liste d'outils du chef. Nécessite Claude Code v2.1.309 ou ultérieure.
• --allowedTools : Claude Code ne transmet pas ce flag à un coéquipier en volet divisé, donc une action que vous avez autorisée uniquement avec celui-ci n'y est pas pré-approuvée. Pour approuver ces actions à l'avance, placez les règles sous permissions.allow dans --settings lorsque vous démarrez le chef. Par exemple, exécutez claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}' dans votre shell. Les règles s'appliquent au chef et à chaque coéquipier en volet divisé pour cette session.

Les demandes de permission des coéquipiers s'affichent dans la session chef ; approuvez-les donc vous-même à cet endroit. Vous n'avez pas besoin d'approuver le plan d'un coéquipier.

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. Si vous démarrez le chef avec --setting-sources, les coéquipiers chargent à partir de la même liste restreinte de sources. Avant la v2.1.281, les coéquipiers en volet divisé chargeaient chaque source de paramètres.

Un coéquipier 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

[!TIP]

Le chef divise le travail en tâches et les assigne aux coéquipiers automatiquement. S'il ne crée pas assez de tâches, demandez-lui de diviser le travail en morceaux plus petits. Avoir 5 à 6 tâches par coéquipier garde tout le monde productif et permet au chef de réassigner le travail si quelqu'un est bloqué.

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 que vous avez demandé à Claude de les lancer :

• En mode in-process, les coéquipiers apparaissent dans le panneau des agents sous la zone de saisie du prompt. Utilisez les touches fléchées haut et bas pour en sélectionner un, puis appuyez sur Enter pour l'afficher.
• Une ligne de coéquipier qui a disparu après être restée inactive a été masquée, et non arrêtée. Les lignes inactives sont masquées 30 secondes après que l'ensemble du panneau devient inactif et réapparaissent au prochain tour du coéquipier. Lorsque plus de trois coéquipiers sont inactifs, leurs lignes excédentaires sont regroupées en une seule ligne N idle agents que Enter permet de développer. Envoyez un message au coéquipier par son nom pour faire réapparaître une ligne masquée.
• Vérifiez que la tâche confiée à Claude était suffisamment complexe pour justifier une équipe. Claude décide de lancer ou non 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 la CLI it2 est installée et que l'API Python est activée dans les préférences d'iTerm2.

Claude lance des coéquipiers au lieu de sous-agents

Lorsque les équipes d'agents sont activées, un sous-agent que Claude nomme dans la session du responsable est lancé en tant que coéquipier. Claude peut nommer des sous-agents de lui-même, ce qui peut donc se produire lors d'une délégation que vous n'avez jamais présentée comme un travail d'équipe.

Pour que les sous-agents nommés soient de nouveau lancés en tant que sous-agents, désactivez les équipes d'agents en définissant CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS sur 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 lance un sous-agent, de sorte que le prochain sous-agent nommé par Claude est lancé en tant que sous-agent.

Définir la variable sur 0 dans votre settings.json utilisateur remplace un export du shell. D'autres sources de paramètres peuvent toutefois encore activer les équipes d'agents :

• Fichiers de paramètres de priorité supérieure : les paramètres de projet, les paramètres locaux et un payload --settings s'appliquent après les paramètres utilisateur, donc une entrée env qui définit la variable sur 1 dans l'un d'eux l'emporte. Consultez Priorité des paramètres.
• Paramètres gérés : les paramètres gérés s'appliquent après toutes les autres sources. Si votre organisation y active les équipes d'agents, 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 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 jusqu'au responsable, ce qui peut créer des frictions. Pré-approuvez les opérations courantes dans vos paramètres de permission avant de lancer des coéquipiers afin de 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 des agents et en appuyant sur Enter en mode in-process, ou en cliquant sur le volet en mode divisé, puis :

• Donnez-leur directement des instructions supplémentaires
• Lancez un coéquipier de remplacement pour poursuivre le travail

Un message du responsable ou d'un autre coéquipier réveille un coéquipier in-process qui attend de réessayer une requête API ayant échoué : il réessaie alors immédiatement au lieu d'attendre la totalité du délai avant nouvelle tentative.

Le responsable peut lui aussi s'arrêter prématurément, en décidant que l'équipe a terminé avant que toutes les tâches ne soient réellement achevées. Si cela se produit, demandez-lui de continuer.

Sessions tmux orphelines

Si une session tmux persiste après la fin de la session Claude Code, elle n'a peut-être pas été entièrement nettoyée. Listez les sessions et mettez fin à 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. 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.
• Pas de modes de permission par coéquipier au moment de la génération : les coéquipiers commencent avec le mode de permission décrit sous Permissions.
• 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