Outils de suivi des dépenses Claude Code comparés

Ce que lit réellement un outil de suivi des dépenses Claude Code

Chaque outil de suivi des dépenses Claude Code lit l’une de trois sources de données. La source détermine la question à laquelle il peut répondre. Un analyseur de journaux lit les fichiers de transcription des sessions enregistrés sur votre propre disque. Un dashboard lit les données d’utilisation qu’Anthropic conserve pour votre compte ou votre organisation. Un backend de métriques lit le flux OpenTelemetry (OTel) émis par Claude Code lorsque vous l’activez. Ces trois outils peuvent être corrects en même temps et produire des résultats différents, car ils ne comptabilisent pas les mêmes éléments.

Ce guide ne réexplique pas les tokens. comment Claude Code comptabilise l’utilisation des tokens décrit les tokens d’entrée et de sortie, les écritures et lectures du cache. Aucun dashboard n’est vraiment utile tant que cette partie n’est pas claire. La question est plus précise : selon le type d’outil, que peut-il voir et que ne pourra-t-il jamais voir ?

Pourquoi trois outils de suivi des dépenses Claude Code sont apparus le même jour

Trois outils distincts de suivi des dépenses Claude Code ont été publiés le même jour. Ce n’étaient pas trois versions du même outil, et c’est ce qui est intéressant. Le premier analysait les fichiers de session locaux. Le deuxième encapsulait les écrans d’utilisation du compte. Le troisième était un backend de traçage hébergé que vous exécutez vous-même.

Ils sont apparus au même moment parce que le coût d’une session d’agent n’était plus évident. Pour une conversation, le coût correspond à peu près à ce que vous voyez à l’écran. Un agent lit vingt fichiers, exécute la suite de tests et renvoie toute la conversation à chaque tour. La facture dépend donc du contexte que vous n’avez jamais saisi. Avec un abonnement, aucun montant en dollars n’est affiché : seule une barre d’utilisation se vide plus ou moins vite selon les jours. Ces trois outils comblent chacun une partie différente de ce manque.

Forme 1 : un analyseur de journaux local vous indique le coût d’aujourd’hui

Claude Code stocke chaque conversation au format JSON Lines (JSONL) dans ~/.claude/projects/<project>/<session-id>.jsonl, où <project> correspond au chemin de votre répertoire de travail, les caractères non alphanumériques étant remplacés par -. Chaque réponse de l’assistant dans ce fichier contient le nombre de tokens de la requête correspondante. Un analyseur de journaux additionne ces valeurs et calcule leur coût.

ccusage est celui que la plupart des utilisateurs choisissent. Aucune installation n’est nécessaire :

npx ccusage@latest daily
npx ccusage@latest daily --breakdown
npx ccusage@latest blocks
npx ccusage@latest session --json

daily effectue le total par date. --breakdown répartit chaque ligne par modèle, ce qui permet de voir qu’un après-midi avec Opus représente parfois la majeure partie de la semaine. blocks regroupe les données selon la fenêtre de cinq heures à laquelle l’abonnement est réinitialisé. session effectue le total par conversation, et --instances regroupe les données par projet afin d’identifier le dépôt le plus coûteux. Ajoutez --since et --until pour délimiter la période, puis utilisez npx ccusage@latest daily --help pour connaître le format de date attendu par votre version. Depuis août 2026, l’outil lit également les données d’autres CLI d’agents, notamment Codex et OpenCode, ce qui est utile pour les comparer.

Les prix proviennent d’une table tarifaire des modèles, et l’outil propose trois modes de calcul des coûts. --mode auto utilise la valeur costUSD écrite par Claude Code dans le fichier lorsqu’elle est présente, et calcule le coût à partir des nombres de tokens dans le cas contraire. --mode calculate calcule toujours le coût à partir des tokens et ignore tout coût enregistré. --mode display affiche uniquement les coûts enregistrés et imprime $0.00 pour les lignes qui n’en contiennent aucun. Si un total semble incorrect, exécutez le même rapport avec calculate, puis avec display. Un écart important entre les deux indique que la plupart des entrées ne contiennent aucun coût enregistré. Les valeurs affichées sont donc des estimations.

Les mêmes données peuvent alimenter votre prompt. ccusage statusline affiche une ligne compacte pour la barre d’état de Claude Code, configurée dans ~/.claude/settings.json comme n’importe quelle autre commande de barre d’état. Consultez créer une barre d’état pour Claude Code pour voir le bloc de configuration et les champs qu’il reçoit.

Un analyseur de journaux ne peut pas voir les activités qui n’ont pas eu lieu sur cette machine. Un second ordinateur portable, une session sur claude.ai ou le travail d’un collègue : ces transcriptions se trouvent sur les disques concernés. Les anciennes données peuvent également manquer, car les transcriptions sont supprimées après 30 jours par défaut avec le paramètre cleanupPeriodDays. Les données du trimestre précédent sont donc perdues si vous ne les avez pas archivées.

Il existe un autre risque, lié à la structure des données. La documentation d’Anthropic indique que le format des entrées est interne à Claude Code et qu’il change d’une version à l’autre. Les scripts qui analysent directement ces fichiers peuvent donc cesser de fonctionner à chaque release. Cela s’applique à tous les outils de ce type. C’est également pourquoi un one-liner jq écrit manuellement sur le JSONL est une moins bonne idée qu’il n’y paraît : les analyseurs maintenus suivent les changements de format, alors que votre one-liner affichera un résultat erroné avec assurance le jour où un champ sera renommé.

Enfin, le montant en dollars doit être interprété avec prudence dans le cadre d’un abonnement. Les offres Pro et Max ne facturent pas les tokens à l’unité. Le montant correspond donc à ce que vos tokens auraient coûté aux tarifs catalogue de l’API. Il mesure l’intensité de votre utilisation. Ce n’est pas le montant de votre facture. Si vous cherchez à déterminer l’offre à choisir, cette comparaison constitue un sujet distinct : consultez facturation de l’API par rapport à un abonnement Claude.

Forme 2 : les écrans d’utilisation intégrés indiquent quel modèle a consommé le budget

Claude Code intègre ses propres rapports, mais la plupart des utilisateurs ne les consultent jamais. Exécutez /usage dans une session. Le bloc Session, en haut de l’écran, affiche le nombre de tokens par modèle et un montant en dollars pour la session en cours. Ce montant est calculé localement à partir du nombre de tokens et des tarifs catalogue standard. Il ne tient pas compte des remises ni des tarifs promotionnels. Il peut donc différer du montant de votre facture. Les totaux sont réinitialisés lorsque /clear démarre une nouvelle conversation.

Avec un forfait Pro, Max, Team ou Enterprise, le même écran indique la part de la limite de votre forfait que vous avez utilisée. Il attribue aussi l’utilisation récente aux skills, aux subagents, aux plugins et à chaque serveur MCP, sous forme de pourcentage du total. Il signale les comportements qui représentent au moins 10% de l’utilisation récente, comme un contexte long ou des échecs de cache. Appuyez sur d ou w pour basculer entre les dernières 24 heures et les 7 derniers jours. Ces chiffres sont approximatifs. Ils sont calculés à partir de l’historique local des sessions sur cette machine. Un autre appareil n’est donc pas pris en compte.

Dès que plusieurs développeurs sont concernés, les chiffres sont rattachés au compte. Une organisation API dispose de la page d’utilisation de la Console, d’un tableau de bord Claude Code indiquant les dépenses et les lignes acceptées par membre, ainsi que d’une API Claude Code Analytics qui renvoie les mêmes métriques quotidiennes par utilisateur avec une clé d’administration. Les forfaits Teams et Enterprise fournissent un rapport des dépenses dans la console d’administration, avec export CSV et mise à jour quotidienne. Enterprise ajoute une API d’analytics. Les éléments auxquels vous avez accès dépendent de la méthode de connexion de chaque développeur. Une organisation hétérogène doit donc consulter deux rapports et additionner les montants manuellement.

Pour dimensionner un budget, la valeur publiée dans la documentation tarifaire d’Anthropic en août 2026 est une moyenne d’environ $13 par développeur et par jour actif, et de $150 à $250 par développeur et par mois. 90% des utilisateurs restent sous $30 par jour actif. Considérez cette valeur comme une référence publiée à partir de déploiements en entreprise, et non comme une prévision pour votre équipe. Lancez un groupe pilote et mesurez les coûts avant toute extrapolation.

Les tableaux de bord ne peuvent pas descendre au niveau de la journée et de l’utilisateur. Ils vous indiqueront qu’Opus a représenté la plus grande part de l’utilisation mardi. Ils ne vous indiqueront pas quel prompt, quel dépôt ou quel job CI en est à l’origine. Ils ont également un décalage, car les rapports d’organisation sont mis à jour quotidiennement. Ils servent donc à analyser l’utilisation, et non à arrêter un agent qui s’emballe dans l’après-midi. Pour arrêter cet agent, il faut des limites, pas des rapports. C’est le sujet de limiter les coûts des agents sur un VPS.

Forme 3 : votre propre stack OpenTelemetry vous indique quel prompt a régressé

Claude Code émet des métriques et des événements OpenTelemetry dès que vous définissez une variable d’environnement. C’est la seule option qui transmet les données de tokens et de coûts par utilisateur vers un système que vous contrôlez, presque en temps réel. Les métriques incluent claude_code.cost.usage en USD, claude_code.token.usage en tokens, claude_code.session.count et claude_code.active_time.total.

La métrique des tokens est la plus intéressante en raison de ses attributs. Chaque point de données contient type, qui correspond à input, output, cacheRead ou cacheCreation, ainsi que model et query_source, qui correspondent à main, subagent ou auxiliary. Il contient également agent.name, skill.name, mcp_server.name et mcp_tool.name. Cela suffit pour répondre à des questions auxquelles aucun dashboard ne peut répondre : quelle part de la facture correspond aux subagents plutôt qu’à vos propres tours, si un serveur MCP a doublé vos tokens d’entrée, ou si les lectures du cache se sont effondrées après la modification de CLAUDE.md par quelqu’un. Le comportement du cache est généralement la principale source de surprise, et quand le prompt caching devient rentable explique ce que vous observez.

Une correction s’impose, car ce point revient dans chaque discussion à ce sujet. Langfuse est un bon backend de tracing auto-hébergé, et son exécution sur un VPS est décrite dans auto-héberger Langfuse pour le tracing d’agents. Son endpoint OTLP accepte uniquement les traces. Claude Code exporte des métriques et des événements de logs, pas des spans. Par conséquent, pointer OTEL_EXPORTER_OTLP_ENDPOINT vers Langfuse laisse le projet vide et ne produit aucune erreur utile à analyser. Langfuse convient aux agents que vous développez directement avec l’API, lorsque votre propre code crée chaque span avec son prompt, son modèle et son coût. Pour le CLI Claude Code, un metrics store est le choix adapté.

Configurer le suivi des dépenses de Claude Code sur votre propre VPS

Deux services suffisent : un collecteur pour recevoir les métriques et Prometheus pour les stocker. Gardez-les tous les deux hors de l’Internet public, car un port OTLP ouvert accepte les écritures de toute personne qui le trouve. Écrivez /opt/ccmetrics/compose.yaml :

services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes:
      - ./collector.yaml:/etc/otel/config.yaml:ro
    ports:
      - "10.8.0.1:4318:4318"
    restart: unless-stopped
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
    restart: unless-stopped

volumes:
  prom-data:

10.8.0.1 est l’adresse du serveur à l’intérieur d’un tunnel WireGuard. Le collecteur est ainsi accessible depuis vos machines, et depuis aucun autre endroit. L’adresse placée devant le port joue ici un rôle réel, car les ports Docker publiés ne sont pas filtrés par ufw : voir pourquoi les ports Docker publiés contournent ufw. La mise en place du tunnel lui-même est décrite dans un VPN WireGuard sur votre propre VPS.

/opt/ccmetrics/collector.yaml :

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889

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

/opt/ccmetrics/prometheus.yml. Le port 8889 n’est jamais publié sur l’hôte, car Prometheus atteint le collecteur sur le réseau Compose en utilisant le nom du service :

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: claude-code
    static_configs:
      - targets: ["collector:8889"]

cd /opt/ccmetrics
docker compose up -d
docker compose logs collector

Les journaux du collecteur doivent se terminer par Everything is ready. Begin running and processing data.. Si les journaux s’arrêtent sur une erreur de configuration, cela signifie que le YAML n’a pas été analysé correctement et que le conteneur redémarre en boucle.

Configurez maintenant Claude Code pour l’utiliser. Sur chaque machine qui exécute Claude Code, ajoutez ceci à ~/.claude/settings.json :

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "none",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://10.8.0.1:4318",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000"
  }
}

Démarrez une session, envoyez un prompt, attendez l’intervalle d’exportation (10 secondes ici, 60 secondes par défaut), puis demandez à Prometheus ce qu’il a appris :

curl -s http://localhost:9090/api/v1/label/__name__/values | grep -o 'claude_code[a-z_]*'

Vous devriez obtenir plusieurs noms commençant par claude_code_. L’exporter remplace les points par des underscores et ajoute l’unité. Les chaînes exactes dépendent donc de la version de votre collecteur. Un résultat vide signifie qu’aucune donnée n’est arrivée. Vérifiez que le protocole et le port correspondent, car http/protobuf utilise le port 4318 et grpc utilise le port 4317. Une incompatibilité échoue silencieusement. Exécutez claude --debug : le journal de debug indique les erreurs d’exportation OTel.

Pour une seule machine et sans serveur, ignorez tout ce qui précède. Définissez OTEL_METRICS_EXPORTER=prometheus : Claude Code expose alors lui-même un endpoint de scraping sur http://localhost:9464/metrics. Lorsque prometheus est le seul exporter indiqué, Claude Code omet les unités USD, tokens et s des noms de métriques afin que le scraping reste au format texte Prometheus valide.

Cette architecture implique un choix de confidentialité. Par défaut, seuls les compteurs quittent la machine. Aucun texte de prompt ni aucune sortie d’outil n’est envoyé. OTEL_LOG_USER_PROMPTS=1 et OTEL_LOG_TOOL_CONTENT=1 modifient ce comportement. Votre serveur de métriques contient alors du code source et tout autre contenu présent dans le contexte. Activez ces options uniquement après réflexion et consultez d’abord éviter les secrets dans le contexte de l’agent.

Suivre les dépenses des exécutions par script et des jobs CI

Les exécutions non interactives sont celles qui surprennent le plus, car personne ne surveille l’écran. claude -p avec --output-format json renvoie le coût de cette exécution dans son résultat :

claude -p "summarise the failing tests" --output-format json | jq '.total_cost_usd'

Le résultat contient total_cost_usd ainsi qu’une ventilation par modèle. Un job CI peut donc enregistrer ses propres dépenses sans utiliser de dashboard. Ajoutez cette valeur à un fichier ou envoyez-la comme métrique au collector indiqué plus haut. C’est le suivi des dépenses utile le moins coûteux disponible, et il nécessite un appel jq par exécution.

Modes d’échec et résultats observés

Le rapport est vide. npx ccusage@latest daily n’affiche aucune ligne, ce qui signifie qu’il ne lit pas l’emplacement où Claude Code écrit ses données. CLAUDE_CONFIG_DIR modifie cet emplacement, et il faut l’indiquer au parser. Si des lignes sont présentes, mais s’arrêtent environ un mois plus tôt, c’est cleanupPeriodDays qui fonctionne comme prévu : les transcriptions sont supprimées au bout de 30 jours par défaut.

Deux machines indiquent des totaux différents. C’est attendu et ce n’est pas un bug. /usage et tout parser de logs ne lisent que l’historique des sessions locales. L’utilisation depuis un autre appareil ou depuis claude.ai est donc absente des deux résultats.

Le total local ne correspond pas à la facture. Les chiffres locaux sont calculés à partir du nombre de tokens et des tarifs catalogue standard. Ils ne tiennent compte ni des tarifs promotionnels ni d’une remise contractuelle. Avec un abonnement, vos tokens ne sont d’ailleurs pas facturés individuellement. La page d’utilisation de la Console fait foi pour la facturation de l’API.

Le coût a augmenté alors que vous faisiez le même travail. Vérifiez d’abord les colonnes relatives au cache. Une longue session renvoie tout son historique à chaque tour. Le tarif du cache s’applique tant que le cache est actif, puis le tarif d’entrée complet s’applique lorsqu’il expire. Une longue interruption entraîne donc le retraitement de toute la conversation. Cela apparaît sous la forme d’un nombre élevé de tokens d’entrée à côté d’un petit nombre de tokens de sortie. La tarification des tokens d’entrée et de sortie explique pourquoi ces deux valeurs évoluent indépendamment.

Une journée avec des subagents semble impossible. Chaque subagent utilise sa propre fenêtre de contexte. La consommation de tokens dépend donc du nombre de subagents exécutés et de la durée de chacun. Seules les données OTel permettent de les distinguer, grâce à l’attribut query_source sur claude_code.token.usage. Un parser de logs affiche le total, mais ne permet pas d’en déterminer la répartition.

FAQ

ccusage indique-t-il ce qui m’est réellement facturé avec une formule Max ?

Non. Avec un abonnement, la facturation ne se fait pas au token. Un parser de logs évalue donc vos tokens aux tarifs API publics et indique ce que le même travail aurait coûté via l’API. C’est une bonne mesure relative de l’intensité d’une journée. Elle permet aussi de comparer des projets ou des modèles entre eux. Pour connaître le montant facturé, consultez la page d’utilisation de la Console pour la facturation API et la page de facturation de la formule pour l’abonnement.

Où Claude Code stocke-t-il les fichiers de session lus par ces outils ?

Dans ~/.claude/projects/<project>/<session-id>.jsonl, où <project> correspond au chemin du répertoire de travail, les caractères non alphanumériques étant remplacés par -. Chaque ligne est un objet JSON correspondant à un message, une utilisation d’outil ou une entrée de métadonnées. CLAUDE_CONFIG_DIR déplace l’ensemble du répertoire, et cleanupPeriodDays dans settings.json contrôle la conservation pendant 30 jours. Anthropic décrit le format des entrées comme interne et susceptible de changer d’une version à l’autre. Utilisez donc un outil maintenu plutôt que votre propre script pour l’analyser.

Puis-je envoyer la télémétrie de Claude Code à Langfuse ?

Pas directement. Le endpoint OTLP de Langfuse accepte les traces, tandis que Claude Code exporte des métriques et des événements de logs, pas des spans. Les données ne peuvent donc pas être reçues. Envoyez les métriques de Claude Code vers un collector OpenTelemetry et stockez-les dans Prometheus. Utilisez Langfuse pour les agents que vous développez vous-même avec l’API. Votre code pourra alors émettre des spans contenant le prompt, le modèle et le coût.

Pourquoi mes valeurs locales ne correspondent-elles pas à la page d’utilisation de la Console ?

Parce qu’elles sont calculées différemment. /usage et les parsers de logs additionnent les compteurs de tokens des fichiers de session présents sur la machine que vous utilisez, puis appliquent les tarifs publics standard. La Console indique le montant réellement facturé à votre organisation, sur l’ensemble des machines et des clés, après application des éventuelles remises. Un écart est normal. Un écart très important indique généralement l’utilisation d’un deuxième appareil, d’un runner CI ou d’un autre membre de l’équipe facturé sur le même compte.

Comment suivre le coût d’une exécution claude -p dans la CI ?

Lancez-la avec --output-format json et lisez total_cost_usd dans le résultat, par exemple avec claude -p "..." --output-format json | jq '.total_cost_usd'. Le même payload contient le détail par modèle et l’ID de session. Enregistrez cette valeur pour chaque job afin d’obtenir les dépenses par pipeline, sans agent, dashboard ni service supplémentaire.