Subagents Claude Code : ce qu'ils coûtent vraiment en tokens

Q: Comment voir l'usage de tokens par subagent ?

Claude Code stocke un transcript par subagent dans ~/.claude/projects/ / /subagents/agent- .jsonl. Chaque message de l'assistant a un objet usage. Dédupliquez par message.id, parce qu'une réponse streamée apparaît sur plusieurs lignes, puis additionnez les tokens d'entrée, d'écriture de cache, de lecture de cache et de sortie. La boucle jq ci-dessus le fait par agent.

Cherchez « Claude Code subagents token usage » et la première page se contredit. Un auteur a réduit sa facturation d'usage de 40 % en confiant les tâches ingrates à des subagents. Un autre a vu Claude Code lancer cinq subagents en parallèle et atteindre la limite Pro en une quinzaine de minutes. Un troisième a compté de 66K à 84K tokens par subagent (18 juillet 2026) avant la moindre ligne de code. Les trois peuvent avoir raison en même temps, parce qu'un subagent met deux coûts en balance : une facture de démarrage fixe, payée à chaque fois, et le contexte qu'il garde hors de votre session principale. Le côté qui l'emporte dépend de la tâche, et vous pouvez lire les deux côtés sur vos propres sessions. Dans cet article, je montre ce qu'un nouveau subagent charge avant de faire quoi que ce soit, comment extraire le vrai nombre de tokens de chaque subagent des fichiers de transcript que Claude Code écrit déjà, et la règle que j'utilise pour décider si une tâche en mérite un.

TL;DR

Un subagent qui n'est pas un fork démarre avec une conversation vide mais une charge de démarrage complète : son propre prompt système, le message de tâche, votre hiérarchie de CLAUDE.md (Explore et Plan la sautent), le git status et les skills préchargés (doc de Claude Code).
Cette charge est écrite dans le prompt cache à partir de zéro. Sur une de mes sessions de septembre 2026, 19 subagents ont chacun écrit entre 12 427 et 40 763 tokens à leur première requête, sans aucune lecture de cache.
L'usage par subagent se trouve dans ~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl. Dédupliquez par identifiant de message avant d'additionner, sinon vous compterez la même requête deux ou trois fois.
Déléguez quand le travail verserait dans votre contexte principal bien plus de tokens que la facture de démarrage, et que le résultat revient sous forme de résumé court. Gardez les petites éditions séquentielles dans la session principale.
Les forks (/subtask) réutilisent le prompt cache du parent : ils coûtent moins cher à démarrer qu'un nouveau subagent pour un travail qui a besoin du même contexte.

Un subagent, vu en tokens

La définition officielle est courte. Un subagent est « une instance Claude isolée avec sa propre fenêtre de contexte. Elle prend une tâche, fait le travail et ne renvoie que le résultat », selon le guide des subagents d'Anthropic (7 avril 2026). Le même article est franc sur le prix : « les subagents ont un surcoût. Chacun démarre son propre contexte, consomme des tokens et ajoute une couche d'indirection entre le développeur et le travail. »

Pour votre facture, « sa propre fenêtre de contexte » a trois conséquences.

D'abord, le subagent ne relit rien de votre conversation. La doc sur ce qui se charge au démarrage précise qu'il « ne voit pas votre historique de conversation, les skills que vous avez déjà invoqués, ni les fichiers que Claude a déjà lus ». Claude écrit un message de délégation qui résume la tâche, et le subagent part de là. Si la réponse dépend de quelque chose que vous avez établi vingt tours plus tôt, le subagent va soit le rater, soit aller le rechercher, et le rechercher coûte des tokens.

Ensuite, tout ce que lit le subagent reste dans son propre contexte. Un grep qui renvoie 3 000 lignes, un log de tests, douze fichiers ouverts pour trouver une fonction : la session principale n'en voit rien, seulement le résumé. C'est l'économie dont parlent les témoignages, et elle se cumule, parce que chaque tour suivant de votre session principale renvoie toute la fenêtre de contexte en entrée.

Enfin, le subagent est une boucle d'agent distincte, avec ses propres tours. Chacun de ses appels d'outils renvoie son contexte grandissant au modèle, exactement comme le fait la session principale. Un subagent qui erre à travers quarante appels d'outils est à lui seul une petite longue session.

Les chiffres d'Anthropic sur le travail multi-agents donnent l'échelle. Dans son compte rendu sur le système multi-agents Research (13 juin 2025), les agents utilisaient environ 4× plus de tokens que les interactions de chat, et les systèmes multi-agents environ 15× plus. La doc des coûts de Claude Code donne un avertissement du même ordre pour les équipes d'agents, qui « utilisent environ 7x plus de tokens que les sessions standard quand les coéquipiers tournent en plan mode ». Les équipes d'agents sont une fonctionnalité expérimentale distincte des subagents ordinaires, mais le mécanisme est le même : chaque instance garde son propre contexte.

La facture de démarrage : ce qui se charge avant le premier appel d'outil

La doc liste ce que contient le contexte initial d'un subagent qui n'est pas un fork. Voici cette liste, avec ce qui compte pour le coût :

Chargé au démarrage	Ce qui en fait la taille	Qui s'en passe
Prompt système	Le prompt propre à l'agent plus les détails d'environnement ajoutés par Claude Code	Personne
Message de tâche	Le prompt de délégation écrit par Claude	Personne
Fichiers CLAUDE.md	Tous les niveaux que charge la session principale, y compris `~/.claude/CLAUDE.md` et les règles du projet	Explore et Plan ; tout agent avec `omitClaudeMd: true`
Git status	Instantané pris au démarrage de la session parente	Explore et Plan
Skills préchargés	Le contenu complet des skills nommés dans le champ `skills` de l'agent	Agents intégrés
Définitions d'outils	Les outils que l'agent a le droit d'utiliser, outils MCP compris	Limité par `tools` / `disallowedTools`

Source : Create custom subagents, « What loads at startup », lu le 17 septembre 2026. La ligne des définitions d'outils est mon ajout : elles font partie de chaque requête au modèle, donc un subagent qui hérite de quarante outils MCP transporte aussi leurs schémas.

La ligne qui surprend le plus, c'est CLAUDE.md. Si vos fichiers CLAUDE.md global et projet totalisent 8 000 tokens, chaque subagent généraliste ou personnalisé que vous lancez transporte ces 8 000 tokens à chacune de ses requêtes. Cinq subagents en parallèle les transportent cinq fois. Le problème des CLAUDE.md trop gros est multiplié par la délégation.

L'autre surprise, c'est le cache. Un nouveau subagent a un prompt système différent de celui de votre session principale : il ne peut donc pas lire le prompt cache que votre session a déjà chauffé. Sa première requête écrit sa charge de démarrage dans le cache. Les forks se comportent autrement : la doc note que « comme le prompt système et les définitions d'outils d'un fork sont identiques à ceux du parent, sa première requête réutilise le prompt cache du parent », ce qui « rend le fork moins cher que le lancement d'un nouveau subagent pour les tâches qui ont besoin du même contexte ». Pour la mécanique des lectures et des écritures de cache, l'entrée du glossaire sur le prompt caching la couvre, et comment le prompt caching réduit le coût d'entrée montre l'effet sur une facture.

Ce que j'ai mesuré sur mes propres sessions

Claude Code écrit un transcript par subagent. La doc en donne l'emplacement : ~/.claude/projects/{project}/{sessionId}/subagents/, un fichier agent-{agentId}.jsonl par subagent. Chaque message de l'assistant dans ces fichiers porte un objet usage avec input_tokens, cache_creation_input_tokens, cache_read_input_tokens et output_tokens.

J'ai ouvert les transcripts de subagents d'une session Claude Code sur ma machine en septembre 2026 (modèle claude-opus-5) et lu la première requête de chaque subagent. Pour les 19 subagents vérifiés :

chaque première requête avait cache_read_input_tokens à 0 ;
cache_creation_input_tokens sur cette première requête allait de 12 427 à 40 763 ;
les valeurs se répartissaient en deux groupes, d'environ 12 400 à 15 600 et d'environ 37 000 à 40 800. Je n'ai pas vérifié quels types d'agents tombent dans quel groupe, donc je n'avancerai pas de cause, même si la ligne CLAUDE.md du tableau ci-dessus est le suspect évident.

Un subagent de longue durée de la même session avait aussi une requête tardive (ligne 481 de son transcript) qui a écrit 253 567 tokens dans le cache sans rien lire. Je n'ai pas confirmé pourquoi le cache a raté à cet endroit. La leçon que j'en tire est plus étroite : un subagent qui tourne assez longtemps peut payer une seconde fois tout son contexte, et vous ne le verrez qu'en regardant le transcript.

C'est une session sur une machine : lisez-la comme un ordre de grandeur, pas comme un benchmark. Elle va dans le même sens que les témoignages publics cités plus haut : la facture de démarrage d'un nouveau subagent se compte en dizaines de milliers de tokens, avant qu'il lise le moindre fichier. La page plus large des statistiques d'usage de tokens de Claude Code rassemble d'autres mesures publiées.

Comment mesurer le coût en tokens de chaque subagent

En février 2026, un utilisateur a ouvert une demande de fonctionnalité pour suivre les tokens par subagent, expliquant qu'« il n'y a aucun moyen de mesurer combien de tokens chaque agent a consommés ». L'issue a ensuite été fermée pour inactivité. Vous n'avez pas besoin de cette fonctionnalité : les fichiers de transcript par agent contiennent déjà les chiffres.

Il y a un piège. Claude Code écrit une réponse streamée sur plusieurs lignes, et ces lignes répètent le même identifiant de message avec le même objet usage. Dans le transcript que j'ai vérifié, une requête apparaissait sur trois lignes distinctes avec un usage identique. Additionnez les lignes naïvement et vous comptez triple. Dédupliquez d'abord par message.id.

Avec jq installé, ceci affiche une ligne par subagent d'une session :

for f in ~/.claude/projects//SESSION_ID/subagents/agent-.jsonl; do
jq -s -c --arg f "$(basename "$f")" '
map(select(.message.usage)) | unique_by(.message.id) | map(.message.usage)
| {agent: $f,
requests: length,
input: (map(.input_tokens) | add),
cache_write: (map(.cache_creation_input_tokens) | add),
cache_read: (map(.cache_read_input_tokens) | add),
output: (map(.output_tokens) | add)}' "$f"
done

Remplacez SESSION_ID par la session voulue (les noms de dossiers sous votre projet sont des identifiants de session). Lisez la sortie avec trois questions :

Le cache_write de la première requête est-il proche du cache_write total ? Alors l'essentiel de ce que vous avez payé, c'est le démarrage, et la tâche était probablement trop petite pour être déléguée.
requests est-il élevé ? Quarante requêtes, ce sont quarante allers-retours, chacun renvoyant le contexte du subagent. Un prompt de délégation plus serré ou une limite maxTurns aide.
Un agent est-il très au-dessus des autres ? C'est celui à ouvrir. En général, il est parti explorer en dehors du périmètre que vous lui aviez donné.

Pour la vue au niveau de la session, /usage et les autres outils de comment mesurer l'usage de tokens d'un agent restent le bon point de départ. La boucle par agent ci-dessus répond à la question plus étroite de savoir quelle délégation en valait la peine.

Sur un abonnement, ce ne sont pas des dollars mais ils comptent quand même : les limites Pro et Max sont consommées par les tokens des subagents comme par les autres, et c'est ainsi qu'un lancement en parallèle peut clore une fenêtre de cinq heures plus tôt que prévu. L'explication des limites d'usage de Claude décrit le fonctionnement de ces fenêtres.

Quand un subagent économise des tokens, et quand il en brûle

Le guide d'Anthropic nomme les cas où la délégation paie : les tâches riches en recherche, les sous-tâches indépendantes qui peuvent tourner en parallèle, et les revues qui ne doivent pas hériter des présupposés de la session principale. Il dit aussi que « pour des tâches plus petites ou étroitement séquentielles, rester dans la conversation principale est en général plus simple ».

En tokens, le point d'équilibre s'énonce simplement. Un subagent économise des tokens quand :

(les tokens que le travail ajouterait à votre contexte principal) × (les tours restants dans votre session principale) est plus grand que (la facture de démarrage) + (le travail propre du subagent) + (le résumé qu'il renvoie).

C'est le premier terme qui fait la différence. Les tokens qui arrivent dans votre contexte principal sont renvoyés à chaque tour suivant. Un log de 30 000 tokens lu au tour 10 d'une session de 60 tours est retraité à chacun des 50 tours restants, surtout sous forme de lectures de cache bon marché mais jamais gratuites, et il pousse la session plus tôt vers la compaction. Le même log lu dans un subagent est payé une fois, dans un contexte qui disparaît quand le subagent rend la main.

Ça donne un partage pratique.

À déléguer :

Les recherches larges. « Trouve tous les endroits où on appelle le client de paiement et dis-moi lesquels passent une option de retry. » La sortie brute de la recherche est grosse, la réponse est une liste.
Le tri des logs et des tests. « Lance la suite et ne rapporte que les tests en échec avec leurs messages d'erreur », comme le suggère la doc. La sortie de tests est l'une des plus grosses sources de contexte gaspillé ; le filtrage de sortie est l'autre remède.
Le travail parallèle indépendant sur plusieurs packages, quand rien ne dépend de l'ordre.
Une revue à froid avant de committer, quand ne pas voir votre conversation est justement l'intérêt.

À garder dans la session principale :

Les éditions sur un ou deux fichiers déjà ouverts. Le subagent les relirait.
Les enchaînements où l'étape deux dépend du détail de l'étape un. Le résumé perd exactement le détail dont vous avez besoin.
Les questions sur ce qui est déjà dans votre contexte. La doc renvoie à /btw pour ça : il « voit tout votre contexte mais n'a pas accès aux outils, et la réponse n'est pas ajoutée à l'historique ».
Tout ce qui est court. Si le travail lui-même fait quelques milliers de tokens, la facture de démarrage seule est plus élevée.

Les réglages qui réduisent la facture

Une fois que vous savez quels subagents vous gardez, quelques réglages de la doc changent ce que chacun coûte.

omitClaudeMd: true sur les agents personnalisés. Il lance le subagent sans les fichiers CLAUDE.md utilisateur, projet et locaux (les fichiers de politique gérée se chargent quand même). La doc fait remarquer que « la conversation principale a toujours votre CLAUDE.md complet quand elle lit les résultats de ces subagents, donc la plupart des règles n'ont pas besoin d'atteindre le subagent lui-même ». Si une règle doit l'atteindre, écrivez-la dans le prompt de délégation. Ce réglage demande Claude Code v2.1.271 ou ultérieur.

Une liste tools serrée. Un agent de recherche en lecture seule n'a pas besoin des outils d'écriture ni de tous les serveurs MCP. Moins d'outils, ce sont des schémas d'outils plus petits à chaque requête et moins de façons de s'égarer. Si les schémas MCP forment l'essentiel de votre charge, le chargement paresseux des MCP traite le problème à la source.

Le champ model. Les valeurs acceptées sont sonnet, opus, haiku, fable, un identifiant de modèle complet, ou inherit. Un agent qui cherche et résume a rarement besoin du modèle choisi pour la session principale. Deux réserves de la doc : la fenêtre de contexte d'un subagent « est dimensionnée par son propre modèle, pas par celui du parent », et CLAUDE_CODE_SUBAGENT_MODEL peut imposer un modèle à tous les subagents, ce qui écrase le choix par agent.

maxTurns. Il plafonne les tours agentiques avant que le subagent s'arrête et renvoie un résultat partiel. C'est un outil grossier, mais il transforme une exploration incontrôlée en exploration bornée, et on peut demander à un subagent qu'on peut reprendre de continuer.

Les forks pour les tâches annexes gourmandes en contexte. Quand la tâche annexe a besoin de ce que votre session sait déjà, /subtask démarre un fork qui réutilise le cache du parent au lieu de payer une nouvelle facture de démarrage.

Le plafond de concurrence. Par défaut, Claude Code refuse de lancer un subagent de plus quand 20 tournent déjà (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS le modifie). C'est une limite de sécurité, pas un budget. Si vous faites tourner des agents sans surveillance, les garde-fous de la sécurité budgétaire des agents de nuit comptent davantage.

Erreurs fréquentes

Additionner les lignes du transcript sans dédupliquer. Les réponses streamées répètent le même usage sur plusieurs lignes. Les totaux par agent sortent deux ou trois fois trop élevés, et la conclusion « les subagents coûtent cher » s'en trouve exagérée.
Déléguer une tâche qui a besoin de la conversation. Le subagent ne voit pas votre historique. Il devine ou relit, et relire est le chemin coûteux.
Un CLAUDE.md lourd plus beaucoup d'agents personnalisés. Chaque subagent généraliste ou personnalisé transporte toute la hiérarchie. Allégez CLAUDE.md ou réglez omitClaudeMd sur les agents qui reçoivent leurs consignes par le prompt.
Demander « un rapport complet ». La valeur de retour atterrit dans votre contexte principal. Demandez la liste, les tests en échec, les trois fichiers : le format de sortie fait partie de l'économie.
Juger sur une anecdote. Les 40 % d'économie et la limite Pro atteinte en 15 minutes sont deux témoignages réels sur des charges différentes. Mesurez les vôtres avant de changer vos habitudes.
Croire que parallèle veut dire moins cher. Des subagents en parallèle finissent plus tôt. Le total de tokens est la somme des factures de démarrage et du travail de chaque agent, quelle que soit la durée réelle.

À faire cette semaine

Lisez la facture des subagents d'une session. Prenez une session récente où Claude Code a délégué, lancez la boucle jq ci-dessus, et notez le cache_write de la première requête de chaque agent. Il vous faut jq et cinq minutes. Vous connaîtrez votre propre facture de démarrage au lieu d'emprunter celle de quelqu'un d'autre.
Repérez les délégations qui n'ont pas payé. Tout agent dont le cache_write total vient surtout de sa première requête, avec une poignée de requêtes, a fait trop peu de travail pour justifier son lancement. Écrivez une ligne dans votre CLAUDE.md qui dit à Claude quels types de tâches garder dans la session principale.
Allégez ce que transporte chaque subagent. Mesurez vos fichiers CLAUDE.md, puis ajoutez omitClaudeMd: true et une liste tools étroite aux agents personnalisés qui font de la recherche ou du tri. Relancez la boucle sur une session comparable et comparez le cache_write de la première requête.
Déplacez volontairement une tâche bruyante dans un subagent. Les lancements de tests ou les recherches larges sont les candidats habituels. Demandez un format de sortie court et fixe, et comparez le contexte de la session principale avant et après avec /context.

FAQ

Les subagents de Claude Code consomment-ils plus de tokens qu'une seule session ?

Au total, en général oui. Chaque nouveau subagent paie une facture de démarrage (prompt système, CLAUDE.md, git status, définitions d'outils) et fait tourner sa propre boucle. Anthropic a mesuré environ 15× les tokens des interactions de chat pour les systèmes multi-agents, dans son compte rendu sur le système Research. Ce que les subagents peuvent réduire, c'est la taille de votre contexte principal, et avec elle le coût de chaque tour suivant. Que le total baisse ou non dépend de la quantité de matière brute que le subagent a gardée hors de la session principale et du nombre de tours qu'il restait à cette session.

Combien de tokens un subagent utilise-t-il juste pour démarrer ?

Ça dépend de vos fichiers CLAUDE.md, du prompt de l'agent, de ses outils et de ses skills préchargés. Sur une de mes sessions de septembre 2026, 19 subagents ont chacun écrit entre 12 427 et 40 763 tokens dans le cache à leur première requête, sans rien lire du cache. Un témoignage public de juillet 2026 a mesuré de 66K à 84K tokens par subagent sur des exécutions complètes. Mesurez les vôtres avec la boucle sur les transcripts de cet article.

Les subagents chargent-ils mon CLAUDE.md ?

Les subagents généralistes et personnalisés chargent tous les niveaux de la hiérarchie CLAUDE.md que charge la session principale, d'après la doc des subagents. Les agents intégrés Explore et Plan la sautent. Un agent personnalisé avec omitClaudeMd: true ne charge que les fichiers de politique gérée. Si une règle doit atteindre un tel agent, mettez-la dans le prompt de délégation.

Comment voir l'usage de tokens par subagent ?

Claude Code stocke un transcript par subagent dans ~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl. Chaque message de l'assistant a un objet usage. Dédupliquez par message.id, parce qu'une réponse streamée apparaît sur plusieurs lignes, puis additionnez les tokens d'entrée, d'écriture de cache, de lecture de cache et de sortie. La boucle jq ci-dessus le fait par agent.

Le subagent Explore coûte-t-il moins cher qu'un subagent généraliste ?

Il démarre plus léger. Explore saute CLAUDE.md et le git status, et il est limité aux outils en lecture seule. Son modèle est hérité de la conversation principale, plafonné à Opus sur l'API Claude : il ne tourne donc jamais sur un modèle plus cher que la session. Son coût total dépend quand même de la quantité de recherche qu'il fait. Explore travaille en un seul passage et ne peut pas être repris : les questions de suivi démarrent une nouvelle instance et une nouvelle facture de démarrage.

Les forks coûtent-ils moins cher que les subagents ?

Au démarrage, oui, pour un travail qui a besoin du même contexte. Un fork lancé avec /subtask hérite de la conversation parente, et sa première requête réutilise le prompt cache du parent parce que son prompt système et ses définitions d'outils sont identiques. Un nouveau subagent écrit son propre cache à partir de zéro. La contrepartie : un fork transporte toute votre conversation, ce qui en fait un mauvais choix quand la tâche annexe n'en a aucun besoin.

Pourquoi des subagents en parallèle ont-ils épuisé ma limite Pro ?

Les limites d'abonnement comptent les tokens de tous les agents. Cinq subagents en parallèle paient cinq factures de démarrage et font tourner cinq boucles en même temps : l'usage arrive donc bien plus vite que dans une seule session qui ferait le même travail à la suite. Un développeur a raconté avoir atteint la limite Pro en une quinzaine de minutes de cette façon, contre une trentaine de minutes en traitement séquentiel. Si les limites comptent plus que le temps réel, demandez à Claude de lancer les sous-tâches l'une après l'autre.

Faut-il passer les subagents sur un modèle plus petit ?

Pour la recherche, le tri et la synthèse, souvent oui, via le champ model d'un agent personnalisé. Gardez deux limites en tête : la fenêtre de contexte du subagent est dimensionnée par son propre modèle, et un modèle plus petit qui comprend mal la tâche peut vous coûter une seconde délégation. Essayez sur un agent bruyant, comparez les totaux des transcripts et la qualité des résumés, puis décidez.