Claude Code : mesurer la consommation par session pour savoir laquelle dévore votre forfait

Lancez plusieurs sessions Claude Code en parallèle et votre limite hebdomadaire fond plus vite que prévu. Vous voulez savoir quelle session la dévore, mais ouvrir /usage ne vous le dira pas.

La réponse courte : en septembre 2026, aucun écran officiel n'affiche la part de consommation de chaque session. /usage vous donne les chiffres de la session en cours, ainsi que la consommation de l'ensemble du forfait, répartie en pourcentages par Skill, sous-agent, plugin et serveur MCP. Si vous la voulez par session, il vous faut agréger les journaux de conversation stockés sur votre propre machine.

Mais comptez ces journaux naïvement et vous vous tromperez. Quand j'ai mesuré les journaux des 7 derniers jours sur ma machine, additionner simplement les lignes donnait un total égal à 2,06 fois la valeur correcte. Pire, même parmi les 12 sessions les plus lourdes seulement, l'ampleur de cette erreur variait de 1,30 à 3,02 fois, si bien que le classement changeait. Cet article passe en revue ce que montrent les écrans officiels, la bonne façon de compter, un script d'agrégation d'une cinquantaine de lignes, et ce que j'ai mesuré.

1. Ce que montrent les écrans officiels, et ce qu'ils ne montrent pas

Voici les principaux endroits officiels qui rendent compte de la consommation (en septembre 2026). Aucun d'eux n'affiche la part de chaque session. Le plus proche est la répartition du forfait dans /usage, mais son axe est la fonctionnalité vers laquelle la consommation est allée, pas la session qui l'a consommée.

Source : documentation officielle Claude Code, Manage costs effectively (/usage, /insights, tableaux de bord des organisations), documentation officielle Claude Code, Desktop (anneau de consommation), Centre d'aide Claude, Usage limit best practices (la page de consommation des paramètres), documentation officielle Claude Code, Monitoring (OpenTelemetry)

Au sujet de la répartition du forfait dans /usage, la documentation dit encore une chose importante : « Les chiffres sont approximatifs et calculés à partir de l'historique local des sessions sur cette machine, si bien que l'utilisation depuis d'autres appareils ou claude.ai n'est pas incluse. » Autrement dit, même la répartition officielle provient au bout du compte de vos journaux locaux. Lisez vous-même ces mêmes journaux et vous pourrez les agréger selon l'axe que les écrans officiels laissent de côté : la session. Si vous avez déjà atteint la limite et voulez vérifier ce qu'il reste, consultez Claude Code : « usage limit reached » expliqué.

2. La réponse se trouve dans vos journaux de conversation locaux

Claude Code enregistre l'intégralité de chaque conversation au format JSONL (un objet JSON par ligne), à raison d'un fichier par session. La documentation indique où ils se trouvent.

Source : documentation officielle Claude Code, Explore the .claude directory

Sur ma machine, le nom du dossier <projet> était le chemin absolu du dossier de travail dont les symboles sont remplacés par - (D:\work\site-a devient D--work-site-a). Les sessions lancées depuis l'onglet Code de l'application desktop étaient écrites au même endroit, avec "entrypoint":"claude-desktop" consigné sur chaque ligne.

Ce que vous agrégez, c'est le usage attaché aux lignes qui consignent les réponses de Claude ("type":"assistant"). Voici une vraie ligne, réduite aux seuls champs utilisés par l'agrégation (ID masqués).

{"type":"assistant","requestId":"req_…","timestamp":"2026-07-25T00:16:37.822Z",
 "message":{"id":"msg_…","model":"claude-opus-5",
  "content":[{"type":"text","text":"…"}],
  "usage":{"input_tokens":2,"output_tokens":255,
           "cache_read_input_tokens":33775,"cache_creation_input_tokens":17265,
           "cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":17265}}}}

Les quatre nombres de usage (entrée, sortie, lecture du cache, écriture du cache) sont des champs officiels des réponses de l'API Claude. Le format du fichier journal lui-même, c'est-à-dire ce qui est écrit sur chaque ligne, n'est pas documenté officiellement. La méthode de comptage de cet article a été vérifiée sur mes propres journaux, de la v2.1.197 à la v2.1.260, et elle pourrait cesser de fonctionner dans de futures versions.

La documentation énonce une autre mise en garde : « Les transcriptions et l'historique ne sont pas chiffrés au repos. Les permissions de fichiers du système d'exploitation sont la seule protection. » Si un outil lit un fichier .env, son contenu se retrouve lui aussi dans le journal. Partager des résultats agrégés avec d'autres personnes ne pose pas de problème, mais soyez prudent lorsque vous transmettez les journaux eux-mêmes ou que vous les faites lire par un outil que vous connaissez mal.

3. Additionnez naïvement et vous obtenez environ le double : quatre pièges

Repérer les lignes usage et tout additionner : c'est l'approche la plus évidente, mais dans mes journaux le total est ressorti à environ deux fois la valeur correcte. Il y a quatre raisons à cela.

Piège 1 : une seule réponse s'écrit sur plusieurs lignes

Une réponse de Claude (une requête API) ne correspond pas forcément à une ligne du journal. Sur ma machine, chaque bloc de contenu, qu'il s'agisse de réflexion, de texte ou d'un appel d'outil, était écrit sur sa propre ligne (plus de 99,9 % des lignes contenaient exactement un bloc), et chacune de ces lignes portait usage. Ce qui identifie une réponse, c'est la paire formée par message.id et requestId.

Sur les 142 345 réponses écrites sur deux lignes ou plus, 76 % avaient exactement le même usage sur chaque ligne. Dans les 24 % restants, la valeur des tokens de sortie différait d'une ligne à l'autre. Pour chaque réponse, gardez donc une seule ligne : celle qui a le plus grand nombre de tokens de sortie. Par ailleurs, 1 903 réponses apparaissaient aussi dans un autre fichier (0,95 % de l'ensemble des tokens). Je n'en ai pas trouvé la cause, mais tout regrouper sur la même clé évite aussi de les compter deux fois.

Piège 2 : les enregistrements des sous-agents se trouvent dans des fichiers séparés

Ne lisez que les fichiers .jsonl principaux et les sous-agents disparaissent entièrement du compte. Dans mes journaux, voici la part des totaux corrects qui provenait des sous-agents.

• Entrée (hors cache) : 42,9 %
• Sortie : 23,2 %
• Écriture du cache : 10,8 %
• Lecture du cache : 6,9 %

Session par session, l'écart est encore plus large : sur les 7 derniers jours, en pondérant par le prix, il allait de sessions à 0 % jusqu'à une session à 54 %. Plus une session confie de travail à des sous-agents, plus elle paraît petite quand on ne compte que le fichier principal.

Piège 3 : les deux erreurs se compensent en partie, mais différemment dans chaque session

Additionnez telles quelles les lignes des fichiers principaux : le piège 1 gonfle le compte tandis que le piège 2 le réduit. Sur les 7 derniers jours, le total est arrivé à 2,06 fois la valeur correcte. Si chaque session était décalée du même facteur, les parts resteraient justes. Dans la pratique, ce n'était pas le cas.

Source : mes propres mesures (les 7 derniers jours au 15 septembre 2026. Pour faciliter la comparaison, ce tableau est le seul à utiliser des nombres de tokens non pondérés, y compris pour la part des sous-agents. Les lettres des sessions correspondent à la figure du début)

Les rangs 2 et 3 se sont inversés, tout comme les rangs 4 et 5, et G, en réalité 9e, est remontée à la 6e place. Que D ressorte petite parce qu'elle s'appuie sur des sous-agents, c'est exactement le piège 2, mais E, avec la même part de sous-agents que D (39 %), est partie dans l'autre sens, à 2,60 fois. Le nombre de lignes sur lesquelles chaque réponse se découpe (la quantité de réflexion et d'appels d'outils qu'elle contient) joue aussi, si bien qu'on ne peut pas prévoir le facteur à l'avance. « Il suffit de diviser par deux » ne fonctionne pas.

Piège 4 : 97 % des tokens sont des lectures du cache

Même une fois le comptage correct, comparer les nombres bruts de tokens fausse l'évaluation du poids de chaque session. Voici de quoi étaient faits les 7 derniers jours.

Les prix unitaires, eux, sont loin d'être égaux. Sur la page de tarification officielle d'Anthropic, les lectures du cache coûtent 0,1 fois le prix d'entrée de base (0,025 fois sur Claude Fable 5.1 et Claude Mythos 5.1), les écritures du cache à 5 minutes coûtent 1,25 fois et celles à 1 heure 2 fois, et la sortie coûte 5 fois le prix d'entrée sur tous les modèles actuels. La session C, qui représentait 12,7 % des tokens, est tombée à 10,4 % une fois pondérée par ces prix.

L'ampleur même des chiffres est parlante. Parmi les 12 premières sessions, les 10 autres que D et E lisaient en moyenne environ 410 000 à 480 000 tokens de contexte par réponse (D et E, qui s'appuient sur des sous-agents, tournaient autour de 240 000 et 310 000). « Claude Code envoie la conversation entière à chaque requête », donc plus une session reste ouverte longtemps, plus chaque requête s'alourdit. Claude Code : qu'est-ce qui dévore vraiment votre contexte ? explique ce mécanisme en détail.

4. Le script d'agrégation

Ce script d'agrégation tient compte des quatre pièges. Il fonctionne avec la seule bibliothèque standard de Python 3 (je l'ai testé sur 3.11). Il se contente de lire les journaux, sans jamais rien modifier ni envoyer. Si vous avez déplacé votre répertoire de configuration avec la variable d'environnement CLAUDE_CONFIG_DIR, c'est là qu'il va lire.

import json, os, sys
from collections import defaultdict
from datetime import datetime, timedelta, timezone
from pathlib import Path

DAYS = float(sys.argv[1]) if len(sys.argv) > 1 else 7
ROOT = Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude") / "projects"
SINCE = datetime.now(timezone.utc) - timedelta(days=DAYS)
# USD per 1M input tokens (output = 5x). First match wins.
PRICES = [("sonnet-5", 2), ("sonnet", 3), ("haiku", 1), ("opus-4-1", 15),
          ("opus-4-2025", 15), ("opus", 5), ("fable", 10), ("mythos", 10)]

best = {}  # one API response = one (message.id, requestId)
for path in ROOT.rglob("*.jsonl"):  # also reads <session>/subagents/*.jsonl
    project = path.relative_to(ROOT).parts[0]
    with path.open(encoding="utf-8", errors="replace") as f:
        for line in f:
            if '"usage"' not in line:
                continue
            try:
                row = json.loads(line)
            except ValueError:
                continue
            msg = row.get("message") or {}
            usage = msg.get("usage")
            ts = row.get("timestamp")
            if row.get("type") != "assistant" or not usage or not ts:
                continue
            if datetime.fromisoformat(ts.replace("Z", "+00:00")) < SINCE:
                continue
            key = (msg.get("id"), row.get("requestId"))
            old = best.get(key)
            if old is None or usage.get("output_tokens", 0) >= old[2].get("output_tokens", 0):
                best[key] = (project, msg.get("model") or "", usage)

totals = defaultdict(lambda: [0, 0.0])  # [tokens, weight]
for project, model, u in best.values():
    p = next((v for name, v in PRICES if name in model), 5)
    read_rate = 0.025 if "5-1" in model and ("fable" in model or "mythos" in model) else 0.1
    inp, out = u.get("input_tokens", 0), u.get("output_tokens", 0)
    read, write = u.get("cache_read_input_tokens", 0), u.get("cache_creation_input_tokens", 0)
    write_1h = (u.get("cache_creation") or {}).get("ephemeral_1h_input_tokens", 0)
    totals[project][0] += inp + out + read + write
    totals[project][1] += p * (inp + out * 5 + read * read_rate
                               + (write - write_1h) * 1.25 + write_1h * 2)

all_tokens = sum(t for t, _ in totals.values()) or 1
all_weight = sum(w for _, w in totals.values()) or 1
print(f"last {DAYS:g} days: {len(best):,} responses")
print(f"{'weight':>7} {'tokens':>7}  project")
for project, (t, w) in sorted(totals.items(), key=lambda kv: -kv[1][1]):
    print(f"{w / all_weight:7.1%} {t / all_tokens:7.1%}  {project}")

Enregistrez-le sous un nom comme usage_by_session.py et passez le nombre de jours en argument. Sans argument, vous obtenez les 7 derniers jours.

python usage_by_session.py        # 7 derniers jours
python usage_by_session.py 1      # dernières 24 heures
python usage_by_session.py 30     # 30 derniers jours

La sortie ressemble à ceci (noms de dossiers masqués). weight est la part pondérée par le prix et tokens la part en nombre brut de tokens.

last 7 days: 19,991 responses
 weight  tokens  project
  32.3%   31.7%  D--work-project-a
  11.1%   11.4%  D--work-project-b
  10.4%   12.7%  D--work-project-c
   7.7%    8.6%  D--work-project-d
   6.4%    5.4%  D--work-project-e

5. Mesure : une session sur 29 a consommé près d'un tiers

Sur les 7 derniers jours, 29 sessions ont été actives sur ma machine. Comme le montre la figure du début, la consommation était concentrée sur une poignée d'entre elles.

Mettre les chiffres côte à côte a fait apparaître trois choses.

D'abord, les sessions en tête sont lourdes à chaque requête. Les 3 premières lisaient en moyenne environ 410 000 à 480 000 tokens par réponse. Ce n'est pas seulement qu'elles ont fait plus de requêtes : elles sont restées ouvertes toute la journée pendant que leur contexte ne cessait de grossir. La documentation souligne aussi que, dans une session laissée ouverte longtemps, même une question d'une ligne entraîne une consommation correspondant à la conversation entière.

Ensuite, les sessions qui s'appuient sur des sous-agents paraissent petites vues depuis la conversation principale. Pour D et E, les sous-agents représentaient respectivement 44 % et 54 % de la consommation pondérée par le prix. En regardant la conversation principale dans la barre latérale, vous ne voyez jamais cette part.

Enfin, plus de la moitié des sessions n'ont presque rien consommé. Votre limite ne fond pas plus vite parce que vous avez beaucoup de sessions ouvertes ; ce sont quelques sessions lourdes qui la font fondre. Si vous voulez agir, commencer par celles-là suffit. Par quoi couper en premier est traité dans Astuces pour économiser les tokens Claude Code et les frais supplémentaires à la limite.

6. Comment lire les chiffres, et où ils s'arrêtent

7. Pour continuer à surveiller à partir de maintenant, utilisez OpenTelemetry

Le point fort de l'agrégation des journaux, c'est que vous voyez immédiatement les 30 derniers jours. Si vous voulez plutôt continuer à surveiller à partir de maintenant, OpenTelemetry, la fonctionnalité de surveillance officielle, convient mieux.

Une fois la fonctionnalité activée, Claude Code exporte une métrique de tokens, claude_code.token.usage (avec les types input, output, cacheRead et cacheCreation), et une métrique de coût, claude_code.cost.usage. Toutes deux portent session.id par défaut (OTEL_METRICS_INCLUDE_SESSION_ID, true par défaut). Comme cela ne passe pas par la lecture des fichiers journaux, les lignes en double du piège 1 n'entrent jamais en jeu, et la consommation des sous-agents est enregistrée séparément sous query_source (main, subagent, auxiliary).

Pour essayer d'abord en local, lancez Claude Code avec l'exportateur configuré pour afficher les données dans votre terminal, comme le montre la documentation.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000
claude

Pour agréger en continu, définissez OTEL_METRICS_EXPORTER=otlp et envoyez les données vers une destination que vous gérez vous-même (un backend de surveillance qui accepte OTLP). Il vous faut mettre en place cette destination, et rien de ce qui précède l'activation n'est enregistré : ce sont là les différences avec l'agrégation des journaux.

Source : documentation officielle Claude Code, Monitoring (noms des métriques, attributs, variables d'environnement)

FAQ

Q1. La répartition du forfait dans /usage ne suffit-elle pas ?
Elle mesure selon un autre axe. La répartition du forfait indique, en pourcentages, vers quels Skills, sous-agents, plugins et serveurs MCP la consommation est allée, et elle n'indique pas quelle session l'a consommée. Pour traquer ce qui épuise votre limite du côté des fonctionnalités, utilisez /usage ; du côté des sessions, utilisez l'agrégation de cet article.

Q2. Puis-je utiliser un outil d'agrégation existant ?
Oui. L'outil non officiel ccusage, par exemple, peut produire des rapports par session à partir des mêmes journaux. Vérifiez deux choses avant d'en utiliser un. D'abord, que tout le traitement reste sur votre machine : les journaux contiennent des résultats d'outils, non chiffrés. Ensuite, sa façon de compter : pour vous assurer qu'il traite les lignes en double et les sous-agents de la même manière, comparez une fois sa sortie avec celle du script de cet article.

Q3. Je veux inclure la consommation d'autres machines et de claude.ai.
Les journaux ne sont conservés que machine par machine, donc vous agrégez sur chaque machine, puis vous additionnez les résultats. Les discussions sur claude.ai ne sont pas consignées dans les journaux de Claude Code. Pour savoir ce qu'il reste de votre forfait dans l'ensemble, les barres de progression de Settings > Usage sur claude.ai sont l'endroit fiable où regarder.

Q4. Je veux conserver mes journaux pour pouvoir agréger aussi une consommation plus ancienne.
Pour les sessions utilisées dans le terminal, augmentez cleanupPeriodDays dans settings.json et elles seront conservées plus longtemps. Les sessions que vous avez démarrées ou poursuivies en dernier dans l'application desktop (ou Cowork) sont déjà conservées quel que soit leur âge depuis la v2.1.248 (pour fixer une limite, utilisez desktopSessionCleanupPeriodDays). Notez toutefois que la documentation cite la réduction de ces valeurs comme moyen de limiter l'exposition de vos journaux. Plus vous les gardez longtemps, plus des enregistrements non chiffrés restent longtemps sur votre machine : gardez-le à l'esprit.

Sources

• Claude Code Docs — Manage costs effectively (le bloc Session et la répartition de l'usage du forfait dans /usage, la mention selon laquelle les chiffres sont calculés à partir de l'historique de cette machine, /insights, les tableaux de bord des organisations, la raison pour laquelle la consommation augmente dans les longues sessions)
• Claude Code Docs — Explore the .claude directory (l'emplacement des journaux, subagents/, les 30 jours par défaut de cleanupPeriodDays et le traitement des sessions de l'application desktop, l'absence de chiffrement)
• Claude Code Docs — Desktop (l'anneau de consommation)
• Claude Help Center — Usage limit best practices (ce qu'affiche Settings > Usage)
• Claude Code Docs — Monitoring (les noms des métriques OpenTelemetry, session.id, les variables d'environnement)
• Claude Platform Docs — Pricing (les prix par modèle, les multiplicateurs du cache)

Articles liés

• Claude Code : qu'est-ce qui dévore vraiment votre contexte ? — pourquoi chaque réponse s'alourdit
• Claude Code : « usage limit reached » expliqué — quand vous atteignez la limite
• Astuces pour économiser les tokens Claude Code et les frais supplémentaires à la limite — par quoi couper en premier
• La limite hebdomadaire de Claude Code et sa réinitialisation anticipée — comment fonctionne la limite hebdomadaire