Consommation de tokens dans Claude Code

Pourquoi votre session de codage coûte ce qu'elle coûte

Chaque facture Claude, qu'il s'agisse d'une facture d'API ou d'une limite d'abonnement, se résume à un seul compteur : les tokens en entrée et les tokens en sortie. La page de tarification donne l'impression que c'est simple : tant de dollars par million de tokens en entrée, tant par million en sortie. Ce qu'elle ne vous dit pas, c'est que dans une session de codage agentique, le côté entrée du compteur tourne bien plus vite que l'intuition ne le suggère, parce que l'intégralité de la conversation est renvoyée à chaque tour. Je vends de l'infrastructure facturée à l'usage depuis quinze ans, et les tokens sont le premier compteur que j'aie vu pour lequel la plupart des clients sont réellement incapables de dire ce qui le fait tourner. C'est la leçon de relève de compteur : ce qu'est un token, ce qui compte comme entrée et comme sortie dans une session agentique, pourquoi la mise en cache des prompts réécrit l'arithmétique, et quels leviers font réellement bouger le chiffre.

Ce qu'est un token, et pourquoi le code coûte plus cher que la prose

Un token est l'unité que le modèle lit et écrit : un fragment de texte, généralement une partie d'un mot. Le glossaire d'Anthropic estime qu'un token Claude vaut environ 3,5 caractères anglais, ce qui représente bien plus d'un token par mot une fois les espaces et la ponctuation comptés. Mille mots de prose dépassent confortablement les 1 300 tokens. Le code pèse plus lourd par ligne : les accolades, les opérateurs, les tirets bas et l'indentation se découpent en davantage de tokens par caractère que l'anglais, et un fichier source de quelques centaines de lignes pèse généralement plusieurs milliers de tokens. Un fichier de 2 000 lignes que l'agent décide de lire représente un achat de tokens à cinq chiffres avant même que quiconque ait écrit une ligne de code neuf.

Deux choses à propos des tokenizers déroutent les gens. Premièrement, ils sont propres à chaque modèle : en juillet 2026, Opus 4.7 et versions ultérieures, Sonnet 5 et Fable 5 utilisent un tokenizer plus récent qui produit environ 30 % de tokens en plus pour le même texte que les modèles Claude précédents (l'augmentation exacte varie selon le contenu), ce qui décale tout ce que vous budgétisez en tokens même si les prix par token n'ont pas augmenté en conséquence. Deuxièmement, tiktoken, la bibliothèque vers laquelle se tourne chaque article de blog, est le tokenizer d'OpenAI et sous-estime Claude d'environ 15 à 20 % sur du texte ordinaire, davantage sur du code. Le seul comptage fiable est le point de terminaison count_tokens, abordé plus bas.

Tout est entrée : ce que le compteur compte réellement

Les gens supposent qu'ils paient pour le code que Claude écrit. Dans une session agentique, c'est la petite ligne de la facture. Les tokens en entrée, au tarif le moins cher mais en volume bien plus élevé, incluent :

• Le prompt système. Les instructions du harnais de Claude Code lui-même, plus votre CLAUDE.md et vos fichiers de mémoire, chargés au début de la session et présents dans chaque requête par la suite.
• Les définitions d'outils. Chaque schéma d'outil que l'agent pourrait appeler. Chaque serveur MCP que vous connectez s'ajoute à cette charge fixe, même si Claude Code diffère désormais par défaut les définitions complètes des outils MCP, de sorte que seuls les noms des outils occupent le contexte jusqu'à la première utilisation d'un outil, ce qui atténue le coût sans l'éliminer.
• Chaque fichier que l'agent lit. Un Read d'un fichier source place l'intégralité de celui-ci dans le contexte, et il y reste.
• Chaque résultat d'outil. Les exécutions de tests, la sortie de grep, le déluge du terminal, les journaux de build : tout revient sous forme de tokens en entrée. Une suite de tests en échec qui affiche 8 000 lignes vient de vous facturer un petit livre.
• L'intégralité de la conversation jusqu'ici, renvoyée à chaque tour. Celle-ci mérite sa propre section.

Le renvoi que personne ne budgétise

L'API de Claude est sans état. Elle ne se souvient pas de votre session d'une requête à l'autre : rien ne s'en souvient. Ainsi, au tour 2, le client envoie le tour 1 plus sa réponse plus votre nouveau message. Au tour 50, il renvoie les tours 1 à 49, chaque fichier lu, chaque résultat d'outil, chaque diff, plus le tour 50. Le modèle relit toute la transcription à chaque fois, et chacun de ces tokens relus est facturé en entrée.

La conséquence : le coût par tour croît à peu près linéairement avec la longueur de la session, et le coût total de la session croît à peu près de façon quadratique. Un message qui coûtait un demi-centime au tour 3 peut coûter vingt fois plus au tour 60, pour la même question d'une seule ligne, parce qu'il transporte soixante tours de fret. C'est le fait unique qui explique la plupart des tickets « pourquoi ma facture était-elle si élevée », et ce n'est pas une bizarrerie propre à Claude : tout produit LLM qui donne l'impression d'avoir un état est une API sans état avec une boucle de renvoi en dessous.

Sortie : ce que vous voyez, plus le raisonnement que vous ne voyez pas

Les tokens en sortie sont les plus chers, cinq fois le tarif d'entrée sur toute la gamme actuelle (5 $/25 $ sur Opus 4.8, 3 $/15 $ tarif affiché sur Sonnet 5, 1 $/5 $ sur Haiku 4.5, en juillet 2026). La sortie inclut le texte et le code que Claude génère, ainsi que les tokens de raisonnement : le raisonnement interne que le modèle effectue avant de répondre. Deux faits importent ici. Le raisonnement est facturé au tarif de sortie et compte dans max_tokens : une réponse d'API qui meurt avec stop_reason: \"max_tokens\" et une réponse tronquée signifie souvent que le raisonnement a consommé le budget avant la réponse. Et sur les modèles actuels, le résumé du raisonnement peut ne pas être affiché du tout : Opus 4.8, Sonnet 5 et Fable 5 l'omettent par défaut, mais le raisonnement a tout de même eu lieu et est tout de même facturé. Invisible ne veut pas dire gratuit.

Claude Code active le raisonnement étendu par défaut parce qu'il améliore de façon mesurable le travail en plusieurs étapes, et le budget par défaut peut atteindre des dizaines de milliers de tokens par requête. Sur des tâches plus simples, vous pouvez le réduire : abaissez le niveau d'effort avec /effort ou dans /model, ou ajustez les paramètres de raisonnement dans /config. C'est un véritable levier de coût, pas une superstition.

La mise en cache des prompts réécrit les calculs

La mise en cache des prompts est la raison pour laquelle la boucle de renvoi ne ruine pas tout le monde. L'API peut mettre en cache un préfixe stable de votre prompt (prompt système, définitions d'outils, historique de conversation) et, à la requête suivante, le servir à une fraction du prix. En juillet 2026, les multiplicateurs sont les suivants : une écriture dans le cache coûte 1,25× le tarif d'entrée de base (2× pour la variante d'une heure), et une lecture dans le cache coûte 0,1×. Les écritures sont une prime ; les lectures sont une remise de 90 %. Une seule lecture rembourse déjà largement la prime d'écriture de 5 minutes.

Claude Code gère la mise en cache pour vous, et dans une session saine, la quasi-totalité de cet énorme renvoi est servie depuis le cache. Mais le cache par défaut vit cinq minutes à partir de sa dernière utilisation. Éloignez-vous pour un café qui s'éternise, revenez, envoyez un message : le cache a expiré, et l'intégralité du préfixe accumulé est réécrite à 1,25× au lieu d'être lue à 0,1×. Sur une session de 150 K tokens, ce seul tour froid coûte plus qu'une douzaine de tours chauds. C'est le résultat contre-intuitif qu'il vaut la peine d'intégrer : un rythme d'inactivité puis de reprise peut coûter plus cher qu'un travail continu, parce que chaque pause d'inactivité au-delà du TTL (sa durée de vie) convertit votre prochain tour d'une lecture bon marché en une réécriture coûteuse. Travaillez par sessions ; ne distillez pas une énorme session au rythme d'un message toutes les dix minutes.

Si vous appelez l'API depuis votre propre application sur un VPS, vous n'obtenez rien de tout cela gratuitement, et la blessure auto-infligée classique est un horodatage ou un identifiant de requête interpolé dans le prompt système, qui change les octets du préfixe à chaque requête et désactive silencieusement la mise en cache. Le signe révélateur est usage.cache_read_input_tokens qui reste à zéro sur des appels d'apparence identique.

La formule, avec un exemple concret

Ignorez quiconque cite un prix fixe du type « une session coûte X $ ». Les sessions varient de deux ordres de grandeur. Ce qui tient, c'est la formule :

turn cost = (uncached input      x base input price)
          + (cache writes        x 1.25 x base input price)
          + (cache reads         x 0.10 x base input price)
          + (output incl. thinking x output price)

session cost = sum over all turns

Exemple concret sur Claude Opus 4.8, qui en juillet 2026 coûte 5 $ par million de tokens en entrée et 25 $ par million en sortie. Un tour de milieu de session transportant 80 000 tokens de contexte accumulé : 75 000 lus depuis le cache, 3 000 nouvellement écrits, 2 000 en entrée fraîche non mise en cache, 1 500 tokens en sortie raisonnement compris.

• Lectures de cache : 75 000 × 0,50 $/M = 0,0375 $
• Écritures de cache : 3 000 × 6,25 $/M = 0,019 $
• Entrée non mise en cache : 2 000 × 5 $/M = 0,010 $
• Sortie : 1 500 × 25 $/M = 0,0375 $

Environ 0,10 $ pour le tour ; cinquante tours de ce type, environ 5 $. Maintenant le même tour après l'expiration du cache : les 80 000 tokens complets réécrits à 6,25 $/M font 0,50 $ avant la sortie, soit environ cinq fois tout le tour chaud, pour un travail identique. Cet écart, c'est toute l'histoire du cache en un seul chiffre.

Pour du calibrage plutôt que de la prédiction : les chiffres publiés par Anthropic pour les déploiements de Claude Code en entreprise, en juillet 2026, font une moyenne d'environ 13 $ par développeur et par jour actif, soit 150 à 250 $ par mois, avec 90 % des utilisateurs restant sous les 30 $ par jour. Votre résultat dépend du choix du modèle, de l'hygiène des sessions et de la taille de la base de code, ce qui est exactement pourquoi les leviers ci-dessous comptent.

Voir votre propre usage

Dans Claude Code, la commande est /usage (/cost fonctionne encore, c'est un alias). Le bloc Session en haut affiche les statistiques de tokens et une estimation de coût calculée localement pour la session en cours ; sur les formules d'abonnement, le même écran affiche les barres de limite de votre formule et une ventilation attribuant l'usage récent aux skills, subagents, plugins et serveurs MCP individuels. Pour une facturation faisant autorité sur les comptes d'API, la page d'usage de la Console Claude est la source de vérité : le chiffre de la CLI est une estimation. /context dessine une grille colorée de ce qui occupe la fenêtre de contexte (prompt système, outils, définitions MCP, fichiers, historique) et c'est le moyen le plus rapide de repérer un CLAUDE.md boursouflé ou un serveur MCP bavard ; passez all pour développer la ventilation complète, élément par élément.

Depuis l'API, chaque réponse vous dit exactement ce qui s'est passé :

response = client.messages.create(model="claude-sonnet-5", max_tokens=2048,
                                  messages=messages)
u = response.usage
total_prompt = u.input_tokens + u.cache_creation_input_tokens + u.cache_read_input_tokens
print(f"uncached={u.input_tokens} written={u.cache_creation_input_tokens} "
      f"read={u.cache_read_input_tokens} output={u.output_tokens}")

Notez que input_tokens n'est que le reste non mis en cache : la véritable taille du prompt est la somme des trois champs d'entrée. Un agent qui a tourné pendant une heure en affichant input_tokens: 4000 n'est pas bon marché ; les 200 000 autres tokens ont été servis depuis le cache. Pour estimer avant d'envoyer, utilisez le point de terminaison de comptage de tokens : son appel est gratuit, il dispose de sa propre limite de débit, et il compte avec le tokenizer du modèle que vous nommez (traitez le résultat comme une estimation proche ; la facturation reflète la requête réelle) :

count = client.messages.count_tokens(model="claude-sonnet-5",
                                     messages=[{"role": "user", "content": big_file}])
print(count.input_tokens)

Jamais tiktoken, pour la raison évoquée plus haut.

Formules d'abonnement contre paiement à l'usage

Les mécanismes de ce guide sont identiques partout ; seul le règlement diffère. Avec une clé d'API, Anthropic facture au paiement à l'usage, par token, aux tarifs publiés : chaque chiffre ci-dessus, c'est de l'argent réel. Sur un abonnement Claude (Pro, Max, Team, Enterprise), l'usage de Claude Code puise dans l'allocation incluse de votre formule à la place : en juillet 2026, c'est une fenêtre de session glissante de cinq heures plus une fenêtre hebdomadaire, partagée entre les modèles et avec le chat claude.ai, et le chiffre en dollars de /usage est informatif plutôt qu'une facture. Épuisez une fenêtre et vous verrez « You've hit your session limit » ou « You've hit your weekly limit » avec une heure de réinitialisation, et changer de modèle avec /model ne restaurera pas l'accès, parce que les fenêtres sont partagées entre les modèles. Les formules peuvent éventuellement activer des crédits d'usage, gérés avec /usage-credits, pour acheter de l'usage au-delà du plafond. Je m'abstiens délibérément d'imprimer les quotas des formules : ce sont les chiffres les plus volatils de tout ce sujet, alors consultez plutôt claude.com/pricing et vos propres barres /usage. Les mécanismes de tokens comptent tout de même sur un abonnement : une session gaspilleuse brûle votre fenêtre exactement comme elle brûlerait des dollars. Pour le côté abonnement, voyez quelle formule Claude correspond à votre usage.

Les leviers qui fonctionnent vraiment

• Cadrez ce que l'agent lit. « Corrige le bug de validation dans auth.py » lit un fichier ; « améliore cette base de code » en lit quarante. Gardez CLAUDE.md léger : il est chargé dans chaque session, alors limitez-le à l'essentiel, et déplacez les instructions propres à un workflow dans des skills qui se chargent à la demande.
• Nettoyez et compactez. /clear entre des tâches sans rapport : le contexte périmé est renvoyé, et refacturé, à chaque message suivant. Au sein d'une longue tâche, /compact Focus on the failing tests and the diff résume l'historique et vous garde à l'écart de la courbe quadratique.
• Choisissez la bonne taille de modèle. Sonnet gère la plupart du codage à 2 $/10 $ par million de tokens au tarif de lancement en juillet 2026 (3 $/15 $ tarif affiché, contre Opus à 5 $/25 $), et Haiku à 1 $/5 $ est le bon outil pour le travail mécanique de subagent comme le tri de journaux. /model permet de changer en cours de session.
• Pré-filtrez les sorties verbeuses. Un hook qui réduit par grep une exécution de tests à ses seuls échecs avant que Claude ne la voie transforme 20 000 tokens de résultat d'outil en 300, et il le fait à chaque futur renvoi de ce tour.
• Regroupez ce qui n'est pas interactif. Pour vos propres pipelines d'API (classification, revue en masse, tâches nocturnes), l'API Batches exécute les mêmes modèles avec 50 % de remise en échange d'une livraison asynchrone.
• Respectez l'horloge du cache. Travaillez par sessions continues. Une session Claude Code détachée dans tmux sur un VPS ne coûte rien pendant qu'elle est inactive : les tokens ne sont dépensés que lorsqu'un tour s'exécute, mais le cache chaud est ce que le temps d'inactivité sacrifie, et le prochain tour paie la réécriture.

FAQ

Combien de tokens une session de codage dans Claude Code consomme-t-elle ?

Il n'y a pas de nombre fixe : un seul tour de milieu de session transporte couramment des dizaines de milliers de tokens de prompt une fois les fichiers et l'historique accumulés, et une session de travail atteint les millions, la plupart servis depuis le cache à un dixième du tarif de base. Pour du calibrage, les chiffres d'entreprise publiés par Anthropic en juillet 2026 font une moyenne d'environ 13 $ par développeur et par jour actif, avec 90 % des utilisateurs sous les 30 $. Exécutez /usage dans votre propre session ; cinq minutes à l'observer valent mieux que n'importe quelle moyenne publiée.

Les tokens de raisonnement coûtent-ils de l'argent même quand je ne peux pas les voir ?

Oui. Les tokens de raisonnement sont facturés comme des tokens de sortie, au tarif le plus cher, et comptent dans max_tokens, et les modèles actuels les facturent même quand l'interface omet le résumé du raisonnement à l'affichage. Si une réponse se tronque avec stop_reason: \"max_tokens\" avant que la réponse visible ne se termine, le raisonnement a probablement consommé le budget. Dans Claude Code, abaissez le niveau d'effort avec /effort pour les tâches qui n'ont pas besoin d'un raisonnement approfondi.

Pourquoi une longue session Claude Code devient-elle plus chère par message ?

Parce que l'API est sans état : chaque tour renvoie l'intégralité de la conversation (chaque fichier lu, résultat d'outil et échange précédent) en entrée facturée, de sorte que le tour 50 transporte les tours 1 à 49 comme du fret. La mise en cache des prompts sert le préfixe répété à environ un dixième du tarif d'entrée de base, mais le préfixe lui-même ne cesse de croître, et toute pause d'inactivité au-delà du TTL du cache convertit le prochain tour en une réécriture à plein tarif. /compact réduit l'historique ; /clear le réinitialise.

Comment vérifier mon usage et mon coût de tokens Claude ?

Dans Claude Code, /usage affiche les statistiques de tokens de la session, une estimation de coût locale et les barres de limite de formule sur les abonnements (/cost est un alias) ; /context montre ce qui remplit la fenêtre. Pour une facturation d'API faisant autorité, utilisez la page d'usage de la Console Claude. Dans votre propre code, lisez response.usage : la somme de input_tokens, cache_creation_input_tokens et cache_read_input_tokens donne la véritable taille du prompt, et estimez à l'avance avec le point de terminaison count_tokens, jamais avec tiktoken.