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

[kuthia]

Pour l’orchestration multi-agents, il va devenir important de savoir comment préserver les résultats sémantiques lors du processus de compression du contexte. Ça fait penser aux sciences cognitives.

[GN⁺]

Avis Hacker News

• Il est intéressant de voir que l’innovation de l’an dernier a surtout été centrée sur l’ingénierie
  De nouveaux concepts comme MCP, les agents ou les skills ont afflué, mais les problèmes de fond comme les hallucinations, l’inexactitude et l’effondrement du contexte ne sont toujours pas résolus
  Ce genre de problème semble ne pouvoir être résolu non par de la simple ingénierie, mais par de la recherche fondamentale
  Les améliorations et annonces actuelles donnent l’impression de faire partie d’un cycle de hype destiné à maintenir les attentes des investisseurs
  Honnêtement, je suis lassé du narratif autour de l’IA, et j’aimerais qu’on passe vite au moment où il sera clair de voir à quoi cette technologie sert réellement

• Ce genre de fonctionnalité est sympa, mais je me demande combien de gens peuvent vraiment faire tourner des agents toute la journée
  En utilisant Cursor, la consommation de tokens était tellement élevée que je suis passé à Ultra, mais j’ai l’impression que l’usage n’est pas proportionnel
  Heureusement, l’écosystème des LLM open source rattrape vite son retard, ce qui est encourageant

  • Je n’arrive même pas à épuiser la limite mensuelle de 200 utilisations de Claude Max. Pourtant je code tous les jours et je fais des tâches assez lourdes
  • En réalité, tout cela est encore au stade expérimental, et ça peut très bien échouer comme Gas Town
  • Beaucoup d’entreprises peuvent embaucher un ingénieur junior à 150 000 dollars par an. Si l’abonnement à l’IA coûte plus cher, il y a un problème
    Et puis ici on parle de Claude Code, pas de Cursor. Je recommanderais plutôt d’essayer Claude Max
  • J’ai l’impression que seuls des startups à deux personnes financées par des VC peuvent se permettre de faire tourner ça toute la journée
  • Claude Code Max offre une valeur 30 fois supérieure au prix du token, donc si on ne l’amortit pas, c’est de sa faute. Ça coûte peut-être même moins cher que l’électricité

• Steve Yegge avait proposé il y a quelque temps l’idée d’un orchestrateur d’agents à une entreprise comme Anthropic
  (Welcome to Gas Town)
  Le fait qu’Anthropic sorte maintenant Agent Teams laisse penser qu’ils s’y préparaient déjà ou qu’ils sont arrivés à la même conclusion
  Quoi qu’il en soit, il est intéressant de voir que la vision de Steve a en quelque sorte été validée. La saison du « dressage de putois » arrivera peut-être bientôt

  • Je ne connaissais ni GasTown ni Beeds, mais j’ai construit quelque chose de similaire. C’était une étape suivante très naturelle
    claude-code-orchestrator
  • J’avais aussi bricolé une structure simple d’équipe d’agents avant la vague GasTown. Je faisais tourner plusieurs instances de Claude dans des sessions tmux, synchronisées avec .claude.lock
    Ça marchait plutôt bien, mais ce n’est pas encore efficace. La vitesse de rédaction des specs et la qualité de la QA restent les goulets d’étranglement
  • En réalité, ce type de structure existait déjà dans les frameworks d’acteurs. Comparé à des systèmes comme Akka, il n’y a rien de vraiment nouveau
    Voir les fournisseurs de LLM apprendre seulement maintenant ce genre de chose donne l’impression qu’ils grandissent en temps réel
    Dire que c’est du Kubernetes pour agents n’est pas exagéré. C’est aussi comme ça que je les relie en local
  • Je ne pense pas que les ingénieurs d’Anthropic aient pu ignorer ce genre d’idée. On en parlait déjà beaucoup aux débuts de ChatGPT
  • En fait, ce type de système multi-agent était déjà très présent sur arXiv et GitHub dès 2023
    À l’époque, les modèles étaient juste moins intelligents et les fenêtres de contexte plus petites ; aujourd’hui, c’est simplement devenu suffisamment faisable

• J’utilise depuis un moment un workflow où plusieurs instances de Claude Code collaborent comme agents CLI basés sur tmux
  Cette nouvelle fonctionnalité d’orchestration est bien plus utile, car elle permet de partager une task list commune et au principal agent de coordonner l’ensemble
  L’outil tmux-cli permet d’automatiser la collaboration entre agents

• Je ne m’y étais jamais mis parce qu’il était évident qu’un jour ce genre de fonctionnalité serait intégré nativement, mais on dirait que le moment est venu de l’essayer

• J’ai peur que mon abonnement à 20 $/mois ne tienne même pas 10 minutes

  • Si on paie de sa poche, il est plus raisonnable d’utiliser Kimi ou GLM
  • Je pense pareil. Je doute que ce genre de structure puisse vraiment créer de la valeur
  • Sur certaines tâches, Haiku a donné de très bons résultats

• Ça ressemble à Gas Town

  • Si un projet devient trop bizarre ou gadget, il y a de fortes chances qu’un clone moins puéril finisse par gagner
  • Mais du coup, où est passé le putois ? Je m’interroge sur le sens de l’humour du marché
  • Je ne sais pas ce qu’est Gas Town, mais j’utilisais déjà une structure proche de Claude Code Agent Teams
    En créant des sous-agents depuis la conversation principale pour répartir le travail, on peut travailler longtemps sans perdre le contexte
  • Le design paraît plus simple. Un agent leader et plusieurs workers, c’est plus propre que le système de rôles complexe de Gas Town
  • Mais l’absence de putois reste regrettable

• Je ne peux pas confier Claude Code en autonomie sur de gros travaux
  Pour maintenir la qualité du code, je dois intervenir directement dans le processus de conception
  Une équipe d’agents risque surtout d’augmenter la charge de revue et de refactorisation

  • Si on encode en skills la structure du codebase et les règles d’usage des patterns, on peut faire superviser cela par des sous-agents
    C’est justement l’essence de cette fonctionnalité : faire collaborer des agents de planification, de conception, de QA et de revue
  • Il est aussi possible d’améliorer la qualité en créant dans Claude un modèle adversarial. Un agent modifie, un autre vérifie
  • De la même façon que les humains découpent les gros travaux, il est efficace de faire définir à Claude un plan et des critères de test
  • En pratique, une fois sur trois ou quatre, il faut retuner ou interrompre le processus. Seules les personnes expérimentées le remarquent
  • Des recherches sont aussi en cours sur la division du travail et la recombinaison des résultats par les LLM
    Article associé

• Je cherche une orchestration multi-LLM avec Opus en principal et Gemini ou Codex comme sous-agents

  • Parmi les outils qui prennent en charge ce type de structure, on trouve Coder-Codex-Gemini, ccg-workflow et claude_code_bridge
    Ce sont tous des projets créés par des développeurs chinois, mais d’après mon expérience ils sont excellents
  • Avec AgentWorkforce/relay, on peut définir le LLM de son choix comme lead/orchestrateur
    J’ai résumé mon retour d’expérience dans ce post Twitter
  • Je code avec Opus et je fais la revue avec Codex. Pour chaque tâche, j’appelle une review skill qui lance Codex
    Code de la review skill, et j’utilise aussi l’analyseur de PR Greptile
  • Ce serait vraiment utile si Cursor ajoutait ce genre de collaboration multi-modèle à l’avenir
  • Comme dans l’exemple Pied-Piper,
    on peut aussi imaginer GPT-5.2 Codex Max pour la planification, Opus 4.5 pour l’implémentation et Gemini pour la revue

• En construisant moi-même une alternative à Beads, j’ai fini par mettre au point un système d’agents synchronisé avec des projets GitHub dans une structure assez proche
  Je prévois de le publier bientôt en open source, et je pense qu’à long terme l’intégration à un système de tickets sera plus utile
  Il est souhaitable de voir émerger davantage d’alternatives agnostiques qui ne dépendent pas d’un agent particulier