Agent Teams - orchestration d’équipe de sessions Claude Code

• Fonctionnalité expérimentale permettant de regrouper plusieurs instances Claude Code en une seule équipe afin de répartir et coordonner le travail en parallèle ; la session lead crée les coéquipiers, attribue les tâches et synthétise les résultats
• Contrairement aux sous-agents existants, les coéquipiers peuvent échanger des messages directement entre eux, et l’utilisateur peut aussi communiquer directement avec chaque coéquipier sans passer par le lead
• Efficace pour les revues de code, l’exploration parallèle d’hypothèses de débogage et les travaux cross-layer comme le frontend, le backend et les tests ; pour les tâches séquentielles ou les modifications dans un même fichier, une session unique est plus adaptée
• Chaque coéquipier dispose de sa propre fenêtre de contexte indépendante, ce qui augmente fortement la consommation de tokens ; le coût peut croître proportionnellement au nombre de coéquipiers
• Prend en charge un mode écran partagé via tmux ou iTerm2 et aide à améliorer la productivité et la qualité des tâches de développement complexes grâce à l’exploration parallèle et à l’automatisation de la collaboration

---

Vue d’ensemble d’Agent Teams

• Coordonne plusieurs sessions Claude Code comme une équipe unique pour exécuter des tâches en parallèle
  • Le lead d’équipe répartit le travail et synthétise les résultats
  • Chaque coéquipier s’exécute individuellement dans une fenêtre de contexte indépendante
• Contrairement aux Subagent, les coéquipiers peuvent s’envoyer des messages directement
• Fonctionnalité expérimentale désactivée par défaut, activable via la variable d’environnement CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Quand utiliser Agent Teams

• Recherche et revue : plusieurs coéquipiers étudient simultanément différents aspects d’un problème, puis partagent leurs résultats et les valident mutuellement
• Développement d’un nouveau module ou d’une nouvelle fonctionnalité : chaque coéquipier prend en charge un fichier ou module distinct pour travailler en parallèle sans conflit
• Débogage fondé sur des hypothèses concurrentes : tester différentes hypothèses en même temps pour identifier plus rapidement la cause
• Coordination cross-layer : affecter des coéquipiers au frontend, au backend, aux tests, etc., afin d’effectuer des modifications simultanées
• Pour les tâches séquentielles, l’édition d’un même fichier ou les travaux à fortes dépendances, une session unique ou des sous-agents sont plus efficaces

Sous-agent vs Agent Team

• Sous-agent : possède sa propre fenêtre de contexte mais ne renvoie les résultats qu’à l’appelant ; l’agent principal gère l’ensemble du travail ; coût en tokens relativement faible
• Équipe d’agents : fenêtres de contexte totalement indépendantes, possibilité d’échange direct de messages entre coéquipiers, auto-coordination via une liste de tâches partagée ; coût en tokens élevé car chaque coéquipier est une instance Claude distincte
• Les sous-agents conviennent aux tâches ciblées où seul le résultat importe ; les équipes d’agents sont adaptées aux tâches complexes nécessitant discussion et collaboration entre coéquipiers

Démarrer sa première équipe d’agents

• Désactivé par défaut ; activez-le en définissant la variable d’environnement CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS à 1 ou en ajoutant cette variable d’environnement dans settings.json
• Une fois activé, décrivez en langage naturel la structure de l’équipe et le travail à effectuer et Claude créera l’équipe, lancera les coéquipiers et coordonnera le travail
  • > I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.
  • Concevoir un outil CLI de suivi des TODO, faire explorer indépendamment le sujet par trois coéquipiers — UX, architecture technique et point de vue critique — puis synthétiser les résultats
  • Ainsi, Claude essaie de créer les coéquipiers à partir de la liste de tâches partagée, d’explorer chaque question, de synthétiser les résultats et de nettoyer l’équipe une fois le travail terminé
• Le terminal du lead affiche la liste complète des coéquipiers et l’état des tâches ; Maj+Haut/Bas permet de sélectionner un coéquipier et de lui envoyer directement un message

Contrôle d’une équipe d’agents

• Choisir un mode d’affichage

  • Mode in-process : tous les coéquipiers s’exécutent dans le terminal principal ; sélection et envoi de messages avec Maj+Haut/Bas ; aucune configuration supplémentaire requise
  • Mode split panes : chaque coéquipier s’affiche dans un volet distinct ; permet de voir les sorties simultanément ; nécessite tmux ou iTerm2
  • La valeur par défaut "auto" utilise split pane en session tmux, sinon in-process
  • Le réglage "tmux" active le mode split-pane et détecte automatiquement tmux et iTerm2
  • Il est possible de forcer le comportement via teammateMode dans settings.json ou avec le flag claude --teammate-mode in-process pour une configuration en session unique

• Définir les coéquipiers et les modèles

  • Claude détermine automatiquement le nombre de coéquipiers selon la tâche, mais il est possible d’indiquer explicitement le nombre exact et le modèle (par ex. Sonnet) avec une commande comme "Create a team with 4 teammates"

• Exiger une validation du plan

  • Pour les tâches complexes ou risquées, appliquer aux coéquipiers un mode plan en lecture seule afin de bloquer l’implémentation jusqu’à validation par le lead
  • Une fois le plan terminé, le coéquipier envoie une demande d’approbation au lead ; si elle est acceptée, l’implémentation commence ; si elle est refusée, le plan est révisé et soumis à nouveau
  • Les critères de décision du lead peuvent être influencés en précisant des conditions dans le prompt (ex. "n'approuver que les plans incluant une couverture de tests")

• Mode délégation (Delegate)

  • Limite le lead à des outils de coordination uniquement (lancement de coéquipiers, messages, arrêt, gestion des tâches) au lieu d’implémenter lui-même
  • Après avoir démarré l’équipe, appuyer sur Maj+Tab pour passer en mode délégation

• Conversation directe avec les coéquipiers

  • Chaque coéquipier étant une session Claude Code totalement indépendante, il est possible de lui transmettre directement des consignes supplémentaires, des questions de suivi ou des changements d’approche
  • En mode in-process : sélection avec Maj+Haut/Bas puis envoi du message, Entrée pour consulter la session, Échap pour interrompre le tour en cours, Ctrl+T pour afficher/masquer la liste des tâches
  • En mode split-pane : cliquer sur le volet concerné pour interagir directement

• Attribution et prise en charge des tâches

  • La liste de tâches partagée permet de coordonner le travail de toute l’équipe ; les états de tâche sont pending, in progress et completed
  • Il est possible de définir des dépendances entre tâches ; une tâche avec dépendances non résolues ne peut pas être prise en charge
  • Le lead peut attribuer explicitement une tâche, ou un coéquipier peut réclamer automatiquement la tâche suivante non attribuée et non bloquée après en avoir terminé une
  • Un verrouillage de fichier est utilisé pour empêcher que plusieurs coéquipiers ne réclament simultanément la même tâche

• Arrêt des coéquipiers et nettoyage de l’équipe

  • Si le lead demande l’arrêt d’un coéquipier précis, celui-ci peut accepter ou refuser en expliquant la raison
  • Lors du nettoyage, le lead supprime les ressources partagées de l’équipe ; si des coéquipiers actifs restent présents, l’opération échoue et il faut d’abord les arrêter

Fonctionnement interne d’Agent Teams

• Parcours de démarrage d’une équipe

  • L’utilisateur demande une équipe : décrire une tâche adaptée au travail parallèle et demander explicitement la création d’une équipe d’agents
  • Claude propose une équipe : si Claude juge qu’un traitement parallèle serait avantageux, il propose de créer une équipe ; l’exécution ne commence qu’après confirmation de l’utilisateur
  • Dans les deux cas, aucune équipe n’est créée sans l’accord de l’utilisateur

• Composants de l’architecture

  • Team lead : session principale Claude Code, chargée de créer l’équipe, lancer les coéquipiers et coordonner le travail
  • Teammates : instances Claude Code séparées, chacune exécutant la tâche qui lui est assignée
  • Task list : liste partagée d’éléments de travail que les coéquipiers prennent en charge puis terminent
  • Mailbox : système de messagerie pour la communication entre agents
  • Les dépendances entre tâches sont gérées automatiquement : lorsqu’un coéquipier termine une tâche, les tâches bloquées sont débloquées sans intervention manuelle
  • La configuration de l’équipe est stockée localement dans ~/.claude/teams/{team-name}/config.json, et la liste de tâches dans ~/.claude/tasks/{team-name}/
  • La configuration inclut un tableau members qui enregistre le nom, l’ID d’agent et le type d’agent de chaque coéquipier

• Permissions

  • Les coéquipiers démarrent en héritant des paramètres d’autorisation du lead ; si le lead s’exécute avec --dangerously-skip-permissions, tous les coéquipiers utilisent aussi ce mode
  • Il est possible de modifier le mode d’un coéquipier après son lancement, mais pas de définir des permissions spécifiques par coéquipier au moment du lancement

• Contexte et communication

  • Chaque coéquipier dispose d’une fenêtre de contexte indépendante et charge au lancement le même contexte de projet qu’une session normale : CLAUDE.md, serveur MCP, skills, etc.
  • L’historique de conversation du lead n’est pas transmis aux coéquipiers ; seul le prompt de lancement l’est
  • Transmission automatique des messages : les messages envoyés par un coéquipier sont automatiquement remis au destinataire, sans polling du lead
  • Notifications d’inactivité : quand un coéquipier a terminé son travail et s’arrête, le lead en est automatiquement informé
  • Liste de tâches partagée : tous les agents peuvent consulter l’état des tâches et réclamer celles qui sont disponibles
  • Deux modes de messagerie existent : message (vers un seul coéquipier) et broadcast (vers toute l’équipe ; à utiliser avec modération car le coût augmente avec la taille de l’équipe)

• Utilisation des tokens

  • Les équipes d’agents augmentent fortement la consommation de tokens par rapport à une session unique, en proportion du nombre de coéquipiers actifs
  • Pour la recherche, la revue ou le développement de nouvelles fonctionnalités, ce surcoût est généralement justifié ; pour les tâches routinières, une session unique reste plus rentable

Cas d’usage

• Revue de code en parallèle

  • Un reviewer unique tend à se concentrer sur un seul type de problème à la fois ; il est donc utile de répartir les critères de revue en domaines indépendants comme la sécurité, les performances et la couverture de tests
  • Chaque reviewer applique un filtre différent à la même PR, puis le lead synthétise l’ensemble des résultats une fois l’analyse terminée

• Investigation fondée sur des hypothèses concurrentes

  • Un agent unique a tendance à arrêter l’exploration dès qu’il trouve une explication ; on compose donc explicitement une équipe avec une structure antagoniste
  • Chaque coéquipier enquête sur sa propre hypothèse tout en essayant simultanément de réfuter la théorie des autres, selon une logique de débat scientifique
  • Cela évite le biais d’ancrage des enquêtes séquentielles et augmente la probabilité que la théorie survivante soit la véritable cause racine

Bonnes pratiques

• Fournir suffisamment de contexte aux coéquipiers : le contexte projet est chargé automatiquement, mais pas l’historique de conversation du lead ; il faut donc inclure dans le prompt de lancement les détails utiles à la tâche
• Ajuster correctement la taille des tâches : trop petites, les tâches font perdre l’avantage à cause du surcoût de coordination ; trop grandes, elles risquent d’avancer trop longtemps sans point de contrôle ; les unités autonomes produisant un livrable clair, comme une fonction, un fichier de test ou une revue, sont bien adaptées
• Si le lead commence à implémenter à la place des coéquipiers, lui indiquer : Wait for your teammates to complete their tasks before proceeding
• Pour une première utilisation, commencer par des tâches de recherche et de revue bien délimitées sans écriture de code (revue de PR, étude de bibliothèque, investigation de bug, etc.)
• Éviter les conflits de fichiers : si deux coéquipiers modifient le même fichier, un écrasement peut se produire ; il faut donc répartir le travail afin que chacun traite un ensemble de fichiers différent
• Vérifier régulièrement l’avancement des coéquipiers, réorienter les approches inefficaces et synthétiser les résultats au fur et à mesure

Dépannage

• Les coéquipiers n’apparaissent pas : en mode in-process, utiliser Maj+Bas pour faire défiler les coéquipiers actifs ; vérifier que la tâche est assez complexe pour justifier une équipe ; si le mode split pane est demandé, vérifier que tmux est installé dans le PATH ; avec iTerm2, vérifier que le CLI it2 est installé et que l’API Python est activée
• Trop de prompts de permission : les demandes d’autorisation des coéquipiers remontent jusqu’au lead ; il est donc utile de pré-approuver les opérations courantes dans les paramètres de permissions avant de lancer les coéquipiers
• Un coéquipier s’arrête après une erreur : consulter sa sortie, lui envoyer directement des consignes supplémentaires ou lancer un coéquipier de remplacement pour poursuivre le travail
• Le lead s’arrête avant la fin du travail : lui demander de continuer ou configurer l’équipe pour attendre la fin des coéquipiers avant de déléguer
• Sessions tmux orphelines : si une session tmux subsiste après la fin de l’équipe, la vérifier avec tmux ls puis la supprimer avec tmux kill-session -t <session-name>

Limitations

• Impossible de restaurer les coéquipiers in-process : /resume et /rewind ne restaurent pas les coéquipiers in-process ; après restauration, le lead peut tenter d’envoyer des messages à des coéquipiers inexistants, ce qui impose d’en relancer de nouveaux
• Retard dans l’état des tâches : si un coéquipier ne marque pas une tâche comme terminée, les tâches dépendantes peuvent rester bloquées ; il faut alors mettre l’état à jour manuellement ou demander au lead de relancer le coéquipier
• Arrêt différé : un coéquipier ne s’arrête qu’après avoir terminé la requête ou l’appel d’outil en cours
• Une seule équipe par session : il faut d’abord nettoyer l’équipe en cours avant d’en démarrer une nouvelle
• Pas d’équipes imbriquées : les coéquipiers ne peuvent pas lancer leur propre équipe ni d’autres coéquipiers ; seul le lead peut gérer l’équipe
• Lead fixe : la session qui crée l’équipe en reste le lead permanent ; il n’est pas possible de promouvoir un coéquipier en lead ni de transférer le leadership
• Configuration groupée des permissions au lancement : tous les coéquipiers démarrent avec le mode de permissions du lead ; il n’est pas possible de définir des permissions par coéquipier au moment du lancement
• Le split pane nécessite tmux ou iTerm2 : le terminal intégré de VS Code, Windows Terminal et Ghostty ne prennent pas en charge le mode split-pane