Suivre la consommation de Claude Code : tokens, coût, équipe

Le premier réflexe d'un CTO face à la facture d'un outil IA est de demander un classement : qui consomme le plus, combien de tokens par développeur, quel coût par tête. C'est le tableau de bord le plus simple à construire, et le plus nuisible. Un classement des « gros consommateurs » récompense celui qui bride l'agent, pénalise celui qui l'utilise bien, et apprend à l'équipe à cacher son usage plutôt qu'à l'améliorer. Une métrique qui change le comportement dans le mauvais sens est pire que pas de métrique.

Ne rien mesurer ne tient pas non plus : on ne pilote pas ce qu'on ne voit pas. Suivre la consommation de Claude Code consiste à relever les tokens et le coût par modèle, par équipe et par tâche, à trois niveaux : le poste du développeur, l'équipe, l'organisation. Cet article monte la mesure niveau par niveau, avec des configurations prêtes à l'emploi, puis pose les indicateurs qui valent quelque chose et les règles qui empêchent la mesure de devenir de la surveillance.

Pourquoi mesurer la consommation de Claude Code en équipe ?

Parce que les trois niveaux ne répondent pas à la même question. Au poste : « ma session dérive-t-elle ? ». À l'équipe : « quel modèle, quelle part de sous-agents, quelle tendance depuis la nouvelle règle ? ». À l'organisation : « combien ça coûte, quels plafonds, quel retour ? ». Le repère de la doc Anthropic sur les coûts : environ 13 $ par développeur et par jour actif, 150 à 250 $ par mois, et moins de 30 $ par jour actif pour 90 % des utilisateurs. Prends-le comme ordre de grandeur pour situer un pilote, pas comme budget. Le cadrage financier complet est dans le coût réel des agents de code pour un CTO.

Un point à poser dès le départ : tous les montants affichés côté client sont des estimations. Claude Code calcule le coût localement, au tarif catalogue, à partir des tokens. Seule la page Usage de la Console Anthropic fait foi pour la facturation. Et sur un abonnement Pro, Max, Team ou Enterprise, le montant en dollars est un indice, pas une dépense : la vraie contrainte, ce sont les limites du plan.

Comment voir sa consommation sur son poste avec la statusline ?

/usage et /context donnent l'état de la session à la demande ; leur lecture détaillée, ligne de cache comprise, est dans l'article sur les leviers natifs d'économie de tokens. La statusline rend la même information permanente, sans commande. C'est un script qui reçoit un JSON de session sur stdin et affiche ce qu'il imprime en bas du terminal. Les champs utiles, documentés dans la doc de la statusline : cost.total_cost_usd, context_window.used_percentage, model.display_name, prompt_cache.hit_ratio et prompt_cache.warm (v2.1.251+), et rate_limits.five_hour.used_percentage, présent uniquement pour les abonnés Pro et Max ou derrière une passerelle avec plafond.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 1
  }
}

#!/usr/bin/env bash
# ~/.claude/statusline.sh (chmod +x, nécessite jq)
input=$(cat)

model=$(jq -r '.model.display_name // "?"' <<<"$input")
cost=$(jq -r '.cost.total_cost_usd // 0' <<<"$input")
ctx=$(jq -r '.context_window.used_percentage // 0' <<<"$input" | cut -d. -f1)
# prompt_cache est absent avant la première réponse
cache=$(jq -r 'if .prompt_cache.hit_ratio == null then "--" else ((.prompt_cache.hit_ratio * 100) | floor | tostring + "%") end' <<<"$input")
# rate_limits : abonnés Pro/Max uniquement
five=$(jq -r '.rate_limits.five_hour.used_percentage // empty' <<<"$input")

printf '[%s] ~$%.2f | ctx %s%% | cache %s' "$model" "$cost" "$ctx" "$cache"
[ -n "$five" ] && printf ' | 5h %.0f%%' "$five"
printf '\n'

Le préfixe ~$ n'est pas décoratif : il rappelle à tout le monde qu'il s'agit d'une estimation. Sur abonnement, c'est la jauge 5 heures qu'il faut regarder. Si tu ne veux pas maintenir ton propre script, ccstatusline (npx -y ccstatusline@latest) propose un configurateur en mode texte avec des widgets de coût, de contexte et de bloc de 5 heures.

Qu'est-ce que ccusage et que lit-il vraiment ?

ccusage lit les fichiers JSONL que Claude Code écrit localement pour chaque session et en tire des rapports par jour, par mois, par session ou par fenêtre de 5 heures, sans rien envoyer nulle part. Il mesure, il ne plafonne rien. À la date de rédaction, il en est à la v20 et couvre aussi d'autres agents (Codex, OpenCode, Gemini CLI).

npx ccusage@latest                              # rapport quotidien
npx ccusage@latest daily --since 2026-10-01     # sur une période
npx ccusage@latest monthly --breakdown          # coût par modèle
npx ccusage@latest session                      # par session
npx ccusage@latest blocks                       # fenêtres de 5 h
npx ccusage@latest daily --instances            # regroupé par projet
npx ccusage@latest daily --json                 # exploitable avec jq ou un cron

Limite structurelle, valable aussi pour /usage : les données sont par machine. Un développeur qui travaille sur son portable, dans un devcontainer et sur un runner de CI a trois historiques disjoints, et les fichiers de session sont purgés selon cleanupPeriodDays (30 jours par défaut). Méfie-toi aussi des moniteurs qui prédisent l'épuisement des quotas : Claude-Code-Usage-Monitor, par exemple, s'appuie sur des limites par plan codées en dur dans son code, alors qu'Anthropic les ajuste sans préavis. Pour l'équipe, il faut un flux centralisé.

Comment suivre le coût de Claude Code avec OpenTelemetry ?

L'export OpenTelemetry est le seul mécanisme qui fonctionne sur tous les modes d'accès (abonnement, Console, Bedrock, Vertex, Foundry) et qui pousse des métriques par utilisateur, en quasi temps réel, vers ta stack. Les données ne partent que vers l'endpoint que tu configures. La doc de monitoring décrit l'activation. En équipe, ne compte pas sur la bonne volonté de chacun : déploie via les managed settings.

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel.interne.example:4317",
    "OTEL_RESOURCE_ATTRIBUTES": "team=backend,cost_center=cc-042"
  }
}

Claude Code ignore volontairement les variables d'exporter OTEL_* posées dans le .claude/settings.json d'un dépôt : un projet cloné ne peut pas rediriger ta télémétrie. Deux métriques portent l'essentiel du pilotage : claude_code.cost.usage (en dollars) et claude_code.token.usage, avec un attribut type qui distingue input, output, cacheRead et cacheCreation. Les deux portent model, effort et query_source, qui vaut main, subagent ou auxiliary. La doc en liste d'autres : sessions, commits, PR créées, temps actif.

• Identité : avec un compte Claude, user.email et organization.id sont renseignés. Avec une clé API ou un cloud, seul un identifiant d'installation l'est ; ajoute l'équipe via OTEL_RESOURCE_ATTRIBUTES.
• Noms masqués : les sous-agents et skills personnalisés apparaissent comme custom. OTEL_LOG_TOOL_DETAILS=1 révèle les vrais noms, mais expose aussi les commandes Bash et les arguments d'outils.
• Cardinalité : session.id est inclus par défaut et multiplie les séries temporelles. Prévois une expiration côté collector.
• Confidentialité : le texte des prompts n'est pas exporté par défaut, seule leur longueur. OTEL_LOG_USER_PROMPTS=1 l'ajoute : ne l'active pas sans raison documentée.

Quelle stack minimale pour un tableau de bord Grafana ?

Un collector OpenTelemetry, un Prometheus et un Grafana suffisent. Piège central : Claude Code émet par défaut en temporalité delta, alors que Prometheus attend des compteurs cumulatifs. Sans conversion, tes courbes sont plates ou fausses. La solution propre est le processor deltatocumulative du collector contrib (stabilité alpha, à surveiller lors des montées de version). Si tu instrumentes déjà une application avec la même stack, comme dans OpenTelemetry avec Symfony, le collector peut être partagé.

# otel-collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  deltatocumulative:        # Claude Code émet en delta, Prometheus veut du cumulatif
    max_stale: 30m
  batch: {}

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889
    metric_expiration: 180m  # purge les séries des sessions terminées

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, deltatocumulative, batch]
      exporters: [prometheus]

# compose.yaml : stack de pilote, ports liés à localhost
services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.163.0
    command: ["--config=/etc/otelcol/config.yaml"]
    volumes:
      - ./otel-collector.yaml:/etc/otelcol/config.yaml:ro
    ports:
      - "127.0.0.1:4317:4317"

  prometheus:
    image: prom/prometheus:v3.15.0
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.retention.time=90d
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"

  grafana:
    image: grafana/grafana:13.2.4
    environment:
      GF_SECURITY_ADMIN_PASSWORD__FILE: /run/secrets/grafana_admin
    secrets: [grafana_admin]
    volumes:
      - grafana-data:/var/lib/grafana
    ports:
      - "127.0.0.1:3000:3000"

secrets:
  grafana_admin:
    file: ./secrets/grafana_admin.txt

volumes:
  prom-data:
  grafana-data:

Le fichier prometheus.yml se limite à un job qui scrape otel-collector:8889. Images épinglées, pas de latest, pas de mot de passe admin en clair : en production, ajoute TLS sur le récepteur OTLP. Quelques requêtes PromQL d'exemple, avec les noms utilisés par le guide de monitoring d'Anthropic. Les noms exacts dépendent de la version du collector et de la stratégie de traduction de l'exporter : vérifie-les sur ton endpoint /metrics avant de construire tes panneaux.

# Coût estimé par modèle sur 24 h
sum by (model) (increase(claude_code_cost_usage_USD_total[1d]))

# Part du coût portée par les sous-agents sur 7 jours
sum(increase(claude_code_cost_usage_USD_total{query_source="subagent"}[7d]))
  / sum(increase(claude_code_cost_usage_USD_total[7d]))

# Taux de cache : cacheRead / (input + cacheRead + cacheCreation)
sum(increase(claude_code_token_usage_tokens_total{type="cacheRead"}[1d]))
  / sum(increase(claude_code_token_usage_tokens_total{type=~"input|cacheRead|cacheCreation"}[1d]))

Que montrent les tableaux de bord d'Anthropic ?

Tout dépend de la façon dont tes équipes s'authentifient. D'après la doc analytics :

• Team et Enterprise : un tableau de bord Claude Code dans claude.ai (utilisateurs actifs, sessions, taux d'acceptation) et, en bêta, des métriques de contribution reliées à GitHub. Les PR concernées reçoivent le label claude-code-assisted, interrogeable via l'API GitHub. Sur Enterprise uniquement, une API Analytics expose les rapports par utilisateur.
• Console (API) : la page Usage, qui fait foi pour la facture, un tableau de bord Claude Code par membre, une API Analytics avec clé Admin, et des plafonds de dépense par workspace.
• Bedrock, Vertex, Foundry : les tableaux de bord Anthropic ne voient pas cet usage. Il reste la facturation cloud et OpenTelemetry.

Les métriques de contribution sont volontairement conservatrices : seules les PR où l'implication de Claude Code est jugée certaine sont comptées, et une réécriture importante par le développeur annule l'attribution. Pour des tarifs négociés, le setting managé modelPricing aligne /usage, la statusline et OpenTelemetry sur tes vrais prix ; il change l'affichage, pas la facture. Les plafonds par utilisateur passent par une passerelle : c'est le sujet d'un article à venir de la série, consacré à Claude Code en entreprise.

Quelles métriques suivre, et lesquelles ignorer ?

Une bonne métrique relie la dépense à un résultat et suggère une action. Un tableau de bord de vingt courbes ne pilote rien : garde trois indicateurs.

• Coût par tâche acceptée : dépense de la période divisée par le nombre de PR mergées. Celui qui dépense plus pour livrer plus n'est pas pénalisé. Attention : la métrique OpenTelemetry de PR compte les PR créées par Claude Code, pas les PR mergées ; croise avec GitHub. Et une PR de trois lignes pèse autant qu'un refactoring de quarante fichiers : lis ce chiffre en tendance, jamais pour comparer deux personnes.
• Taux de cache : cacheRead / (input + cacheRead + cacheCreation). Une chute brutale signale une régression de configuration (outils ou instructions qui changent entre les requêtes, serveur MCP instable).
• Part des sous-agents : la fraction du coût portée par query_source="subagent". Une hausse sans hausse des tâches acceptées appelle un examen des workflows, pas un reproche.

À ignorer : les lignes de code générées et le nombre de prompts, qui mesurent l'activité, pas la valeur. Le décalage entre activité et productivité réelle est documenté dans le paradoxe de productivité des agents de code. Une seule alerte utile : une équipe qui dépasse deux à trois fois sa médiane sur 24 heures. Cherche d'abord un Opus laissé par défaut, une session de plusieurs heures jamais vidée ou une tâche planifiée qui tourne en boucle.

Comment éviter la dérive vers la surveillance individuelle ?

Le risque est organisationnel avant d'être technique : les données existent, quelqu'un finira par demander le détail par personne. Un développeur qui se sent surveillé réduit son usage ou le dissimule, et le tableau de bord devient faux. La confiance fait partie de la qualité de la donnée. Pose ces règles avant de déployer :

• Agréger par équipe dans les tableaux de bord partagés ; le détail par poste reste côté développeur (statusline, ccusage).
• Ne pas collecter le contenu des prompts ni le détail des commandes sans finalité écrite.
• Annoncer à l'équipe ce qui est mesuré et pourquoi. En France, user.email est une donnée personnelle de salarié : finalité au registre RGPD et information des représentants du personnel si nécessaire.
• Écrire noir sur blanc que ces données ne servent pas aux évaluations individuelles.

Par où commencer cette semaine ?

• Semaine 1, le poste : une statusline commune versionnée dans un dépôt d'outillage, et ccusage pour ceux qui veulent leur historique. Aucune infrastructure.
• Mois 1, l'équipe : OpenTelemetry via managed settings, collector, Prometheus et Grafana, trois panneaux (coût par modèle, taux de cache, part des sous-agents). Information des équipes en amont.
• Trimestre 1, l'organisation : tableaux de bord Anthropic, métriques de contribution GitHub, plafonds de dépense, modelPricing si tes tarifs sont négociés.

Une fois la consommation visible et comprise, elle devient un outil d'amélioration plutôt qu'une source d'inquiétude : tu sauras si le choix des modèles, les leviers natifs ou un outil tiers ont réellement changé quelque chose. Ces mesures ne servent que si toute l'équipe partage la même lecture des chiffres, et c'est en général là que se joue l'adoption. Prochain article de la série : les Claude Code Mods, qui transforment l'agent en plateforme extensible.

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours