C'est quoi un token chez Claude, et comment ça marche ? On en a compté 3,8 milliards

Le mot est partout autour de Claude : dans la grille de prix, dans le message de limite, dans /usage, dans chaque article qui promet de faire des économies. Presque personne ne dit ce qu'est un token, et le chiffre que les gens regardent est rarement celui qui compte. Ce que Claude écrit en retour pèse une fraction de pour cent de ce qu'une session de code décompte.

Alors on a compté les nôtres. Trente jours de sessions Claude Code sur un Mac, du 10 septembre au 9 octobre 2026 : 388 sessions, 19 668 requêtes au modèle, 3,8 milliards de tokens. Voici ce qu'est un token, les quatre façons dont Claude les compte, et à quoi ressemblent ces chiffres sur du vrai travail.

Un token est un morceau de texte, et la taille du morceau change

Un modèle ne lit ni des lettres ni des mots. Il lit des tokens : des morceaux de texte tirés d'un vocabulaire fixe, parfois un mot court entier, souvent un bout de mot, parfois un seul caractère ou un octet pour quelque chose qu'il n'a jamais vu. Tout se compte dans ces morceaux : ce que tu envoies, ce que Claude écrit, ce qu'il garde d'un tour à l'autre.

La quantité de texte qui tient dans un token dépend du modèle et de la langue. Le glossaire d'Anthropic donne environ 3,5 caractères anglais par token sur les modèles antérieurs à Claude 4.7, et indique que Claude 4.7 et les suivants utilisent un nouveau tokenizer qui produit environ 30 % de tokens en plus pour le même texte. Le compte exact ne sort que de l'endpoint de comptage de tokens, avec le modèle que tu comptes utiliser.

On a mesuré le ratio sur notre propre texte. Nos agents répondent en français, donc on a pris les réponses en texte seul, sans réflexion, sans appel d'outil, sans bloc de code, d'au moins 80 mots : 296 réponses réparties entre Opus 5, Opus 5.5, Fable 5.1 et Sonnet 5.5. La médiane : 2,3 caractères par token, environ 2,6 tokens par mot. Le code, le JSON et les écritures non latines donnent d'autres ratios. L'intérêt n'est pas le chiffre exact : un token est plus petit qu'un mot, et tu ne les comptes jamais à la main.

Chaque requête est comptée sur quatre compteurs

Claude Code écrit chaque session dans une transcription JSONL sous ~/.claude/projects/. Chaque réponse du modèle porte un bloc usage. En voici un vrai, tiré de nos transcriptions, avec les champs utiles :

"usage": {
  "input_tokens": 2,
  "cache_creation_input_tokens": 51836,
  "cache_read_input_tokens": 24882,
  "output_tokens": 315,
  "output_tokens_details": { "thinking_tokens": 54 },
  "cache_creation": {
    "ephemeral_1h_input_tokens": 51836,
    "ephemeral_5m_input_tokens": 0
  }
}

Quatre compteurs, qui ne coûtent pas la même chose :

• input_tokens : la partie du prompt qui n'est ni écrite dans le cache ni lue depuis le cache, facturée au prix d'entrée de base. Dans Claude Code, c'est presque toujours une poignée de tokens, parce que presque tout passe par le cache.
• cache_creation_input_tokens : la partie du prompt stockée dans le cache pour que la requête suivante la réutilise. Une écriture de cache coûte 1,25 fois le prix d'entrée pour un cache de 5 minutes et 2 fois pour un cache d'une heure. Dans nos transcriptions, 97 % des écritures étaient du cache d'une heure.
• cache_read_input_tokens : la partie du prompt rejouée depuis le cache. Une lecture de cache coûte 0,1 fois le prix d'entrée sur la plupart des modèles, 0,05 fois sur Opus 5.5 et Sonnet 5.5, et 0,025 fois sur Fable 5.1 (page prompt caching d'Anthropic, vérifiée le 10 octobre 2026).
• output_tokens : ce que Claude écrit, réflexion comprise. La sortie coûte 5 fois le prix d'entrée sur tous les modèles actuels : 20 dollars le million sur Opus 5.5, 25 sur Opus 5, 50 sur Fable 5.1, 10 sur Sonnet 5.5.

Les trois premiers additionnés donnent le contexte que le modèle a lu pour cette requête. Le quatrième, c'est la réponse.

À quoi ressemblent 30 jours de nos sessions

Sur les 19 668 requêtes, comptées une fois par requête (un même appel d'API peut occuper plusieurs lignes d'une transcription) :

La colonne du coût valorise chaque requête avec son propre modèle et sa propre durée de cache. On ne paie pas cette somme : ces sessions tournaient sur un abonnement. C'est le poids de chaque compteur, la même pondération qu'AgentsRoom utilise pour répartir le pourcentage d'un forfait entre les projets.

Trois lectures.

Presque chaque token est la conversation relue. 97,7 % des tokens sont des lectures de cache. 99,2 % des requêtes lisent quelque chose dans le cache. Quand quelqu'un dit qu'une session « a consommé 50 millions de tokens », c'est ça qu'il regarde.

Ce que Claude écrit pèse peu en tokens, et pas peu en coût. 0,34 % des tokens, 16,8 % de la facture, parce que la sortie est le token le plus cher qui existe. La réflexion faisait 29 % de cette sortie.

Les écritures de cache sont la mauvaise surprise. 2 % des tokens, 37 % du coût. On pensait qu'elles venaient de l'expiration du cache, mais seules 16 requêtes sur 19 668 ont dû réécrire un contexte froid, dont sept après plus d'une heure de silence. 79 % des écritures, c'est simplement chaque nouveau message et chaque résultat d'outil stocké une fois, au double du prix d'entrée, avant d'être relu à chaque tour suivant. Les 20 % restants sont la première requête de chaque session.

Pourquoi une session s'alourdit à chaque tour

Le modèle ne garde rien entre deux requêtes. Claude Code renvoie tout à chaque fois : le prompt système, les définitions d'outils, CLAUDE.md, chaque message, chaque fichier lu, chaque sortie de commande. Le cache rend la partie répétée peu chère par token, pas gratuite, et pas plus petite.

Contexte médian lu par requête, selon sa position dans la session :

La requête médiane lisait 179 000 tokens de contexte pour écrire 290 tokens de réponse. Ce rapport raconte à lui seul les tokens d'un agent de code : la réponse est courte, la lecture est longue, et la lecture grossit avec la session.

Notre première requête est lourde, 52 000 tokens avant que quiconque ait tapé quoi que ce soit, parce que nos agents démarrent avec un long brief de rôle et quatre serveurs MCP dont les définitions d'outils sont dans le prompt. Une session Claude Code nue dans un dossier vide démarre bien plus bas. /context montre ce que la tienne transporte avant le premier message.

Ce qu'une session consomme

Sur les 380 sessions d'au moins trois requêtes :

• 33 requêtes en médiane, de 16 à 61 pour la moitié centrale.
• 27 000 tokens de sortie en médiane, de 12 000 à 48 000.
• 5,4 millions de tokens traités en médiane, de 1,5 à 10,7 millions pour la moitié centrale, dont 5,1 millions de lectures de cache.
• 181 000 tokens écrits dans le cache ou envoyés hors cache en médiane : la partie vraiment nouvelle.
• 4,55 dollars au tarif public de l'API en médiane, de 1,81 à 9,25 pour la moitié centrale.

La réponse honnête à « combien de tokens consomme une session de code », c'est donc une fourchette d'environ un à dix millions, presque entièrement le même contexte relu. Une session qui tourne tout l'après-midi sur une seule longue tâche est en haut de la fourchette ; une session qui corrige un bug et s'arrête est en bas.

Ce que comptent vraiment la fenêtre de 5 heures et la semaine

Sur un forfait Pro ou Max, tu ne vois jamais de solde de tokens. Le centre d'aide d'Anthropic dit que les deux forfaits ont une limite de session de cinq heures et une limite hebdomadaire, que ces limites sont partagées entre Claude et Claude Code (IDE compris), et que les forfaits Max ont une limite hebdomadaire séparée pour Fable. Il ne publie aucun chiffre en tokens pour aucune d'elles. /usage affiche un pourcentage de chaque fenêtre, et l'heure à laquelle elle se réinitialise.

Ce qui fait bouger ce pourcentage, dans la liste d'Anthropic elle-même : la longueur du message, la taille des pièces jointes, la longueur de la conversation en cours, l'usage des outils, le choix du modèle, le niveau d'effort, et les tâches en plusieurs étapes. Lue avec les tableaux ci-dessus, « la longueur de la conversation en cours » est celle qui domine une session de code : le contexte lu à chaque requête passe de 52 000 à 237 000 tokens en cinquante requêtes. Le centre d'aide dit aussi que le contenu mis en cache dans les projets compte moins dans tes limites quand il est réutilisé, ce qui est la même idée que le prix d'une lecture de cache.

On ne sait pas comment Anthropic convertit des tokens en pourcentage d'une fenêtre, et on n'inventera pas de conversion. Ce que les données disent, c'est qu'une requête tardive dans une longue session compte plusieurs fois ce que compte une requête du début, pour la même question.

Ce qui change le compte, en pratique

Quatre leviers, dans l'ordre où ils pèsent sur nos données :

• /clear entre deux tâches sans rapport. Anthropic l'appelle « le levier le plus efficace, pour la qualité comme pour le coût ». Une nouvelle tâche dans une vieille session paie le contexte de l'ancienne à chaque requête.
• /compact quand tu prolonges une longue session. Il remplace l'historique par un court résumé, donc les requêtes suivantes lisent moins.
• Surveille ce qui entre dans le contexte. Une lecture de fichier ou une sortie de commande de 20 000 tokens est écrite une fois au double du prix d'entrée, puis relue à chaque requête suivante jusqu'à la fin de la session. Lire les lignes dont tu as besoin plutôt que le fichier entier paie deux fois.
• Modèle et effort. La réflexion faisait 29 % de notre sortie, et la sortie est le token le plus cher. Un niveau d'effort plus bas sur le travail de routine baisse la sortie, et un modèle moins cher baisse tous les prix d'un coup.

Ce qui n'a pas pesé sur nos données : laisser une session inactive. Avec le cache d'une heure que Claude Code utilise dans nos transcriptions, une réécriture à froid est arrivée 16 fois en 30 jours.

Pour d'autres façons de dépenser moins, lis comment réduire tes coûts de tokens Claude Code.

Compte les tiens

Le tableau ci-dessus sort d'un script sans dépendance. Il lit toutes les transcriptions Claude Code de la machine, compte chaque requête une fois, et affiche les quatre compteurs et les médianes par session. Ajoute un filtre sur o["timestamp"] si tu veux une fenêtre de temps.

import json, glob, os, statistics as st
from collections import defaultdict

FIELDS = ("input_tokens", "cache_creation_input_tokens",
          "cache_read_input_tokens", "output_tokens")
totals, sessions = defaultdict(int), []
for path in glob.glob(os.path.expanduser("~/.claude/projects/*/*.jsonl")):
    seen, session = set(), defaultdict(int)
    with open(path, errors="ignore") as fh:
        for line in fh:
            try: o = json.loads(line)
            except ValueError: continue
            msg = o.get("message") or {}
            usage = msg.get("usage") if isinstance(msg, dict) else None
            if o.get("type") != "assistant" or not usage: continue
            rid = o.get("requestId") or o.get("uuid")
            if rid in seen: continue   # one API call can span several lines
            seen.add(rid)
            session["requests"] += 1
            for f in FIELDS:
                n = usage.get(f) or 0
                totals[f] += n
                session[f] += n
    if session["requests"] >= 3: sessions.append(session)

grand = sum(totals[f] for f in FIELDS)
for f in FIELDS:
    print(f"{f:30s} {totals[f]:>15,} {100 * totals[f] / grand:6.2f}%")
for key in ("requests", "output_tokens", "cache_read_input_tokens"):
    print(f"median per session, {key}: {st.median(s[key] for s in sessions):,.0f}")

Compare tes parts aux nôtres. La ligne des lectures de cache, c'est la conversation relue, et la ligne des écritures, c'est ce qui était nouveau : ces deux-là en disent plus sur ta facture que la ligne de sortie.

Où AgentsRoom l'affiche

Le script te donne un mois. Pendant que tu travailles, AgentsRoom affiche les mêmes compteurs par agent : un badge de tokens dans le composer de chaque session qui passe au rouge quand une session devient lourde, un moniteur de session avec l'entrée, la sortie, les écritures de cache, les lectures de cache et le taux de réussite du cache, et une trace de session qui rejoue la session tour par tour pour montrer quelle lecture de fichier ou quel résultat d'outil a rempli le contexte. Le panneau Usage répartit le pourcentage que publie ton forfait entre tes projets et tes agents, en pondérant chaque session par ce qu'elle coûterait au tarif de l'API, la même pondération que le tableau ci-dessus.

Ce qu'aucun de ces écrans ne te donne, c'est un solde de tokens, parce que ton forfait n'en a pas. Pour cette question, lis combien de tokens il te reste sur Claude. Pour la vitesse à laquelle arrivent ces tokens de sortie, lis les tokens par seconde de Claude Code, mesurés.

Questions fréquentes

C'est quoi, un token chez Claude ?

L'unité dans laquelle Claude lit et écrit du texte : un morceau de mot, parfois un mot court entier, parfois un seul caractère ou un octet. Anthropic précise que la taille dépend du modèle et de la langue : sur les modèles antérieurs à Claude 4.7, un token faisait environ 3,5 caractères anglais, et Claude 4.7 et les suivants utilisent un nouveau tokenizer qui produit environ 30 % de tokens en plus pour le même texte. Tout ce que fait Claude se compte en tokens : ce que tu envoies, ce qu'il répond, et ce qu'il garde dans son cache d'un tour à l'autre.

Combien de caractères ou de mots fait un token Claude ?

Ça dépend de la langue et du texte. Anthropic donne environ 3,5 caractères anglais par token sur les modèles antérieurs à Claude 4.7, et environ 30 % de tokens en plus pour le même texte sur Claude 4.7 et les suivants. Sur 296 réponses en texte seul que nos agents ont écrites en français en septembre et octobre 2026, un token faisait 2,3 caractères, soit environ 2,6 tokens par mot. Le code, le JSON et les écritures non latines donnent d'autres ratios. Pour un compte exact, l'endpoint de comptage de tokens d'Anthropic prend le texte et le modèle.

Pourquoi Claude Code consomme-t-il autant de tokens ?

Parce que chaque requête renvoie toute la conversation : le prompt système, les définitions d'outils, CLAUDE.md, chaque message et chaque résultat d'outil depuis le début. Sur nos 19 668 requêtes, la requête médiane portait 179 000 tokens de contexte pour écrire 290 tokens de réponse, et le contexte passait de 52 000 tokens à la première requête d'une session à 237 000 après cinquante requêtes. Le cache rend cette relecture peu chère par token, mais elle est comptée quand même.

Combien de tokens consomme une session Claude Code typique ?

Sur nos 380 sessions d'au moins trois requêtes, enregistrées entre le 10 septembre et le 9 octobre 2026 : 33 requêtes en médiane, 27 000 tokens de sortie et 5,4 millions de tokens traités au total, dont 5,1 millions de lectures de cache. La moitié des sessions se situait entre 1,5 et 10,7 millions de tokens. Au tarif public de l'API, cette session médiane aurait coûté environ 4,55 dollars ; sur un forfait Pro ou Max, le même travail est décompté des fenêtres de 5 heures et de la semaine.

Les tokens de réflexion comptent-ils ?

Oui. Les tokens de réflexion font partie de output_tokens dans chaque bloc usage, avec un champ thinking_tokens qui dit quelle part de la sortie était de la réflexion. Ils sont facturés au prix de la sortie sur l'API, et Anthropic cite le niveau d'effort parmi ce qui fait avancer plus vite les limites d'un forfait. Dans notre corpus, la réflexion représentait 29 % de tout ce que les modèles ont écrit.

Quelle différence entre une écriture de cache et une lecture de cache ?

Une écriture de cache stocke une partie du prompt pour que la requête suivante la réutilise, et coûte plus que l'entrée simple : 1,25 fois le prix d'entrée pour un cache de 5 minutes, 2 fois pour un cache d'une heure. Une lecture de cache réutilise cette partie stockée et coûte beaucoup moins : 0,1 fois le prix d'entrée sur la plupart des modèles, 0,05 fois sur Opus 5.5 et Sonnet 5.5, 0,025 fois sur Fable 5.1. Dans nos sessions, les lectures de cache faisaient 98 % des tokens et 46 % du coût au tarif public ; les écritures de cache, 2 % des tokens et 37 % du coût.