Quel outil pour suivre les dépenses de Claude Code ?

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

Chaque outil de suivi des dépenses Claude Code lit l’une de trois sources de données, et cette source détermine la question à laquelle il peut répondre. Un analyseur de journaux lit les fichiers de transcription des sessions sur votre propre disque. Un tableau de bord lit les enregistrements 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 tout en affichant des résultats différents, car ils comptent des éléments différents.

Ce guide ne réexplique pas les tokens. comment Claude Code compte l’utilisation des tokens décrit les tokens d’entrée et de sortie, les écritures et les lectures du cache ; aucun tableau de bord n’est réellement compréhensible tant que ce point n’est pas clair. La question est plus ciblée : pour chaque type d’outil, que peut-il voir et que ne pourra-t-il jamais voir ?

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

Trois outils distincts de suivi des dépenses de Claude Code ont été publiés le même jour. Il ne s’agissait pas de trois versions du même outil, et c’est ce qui les rend utiles. 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 en même temps parce que le coût d’une session d’agent n’était plus évident. Une conversation coûte à peu près ce que vous voyez à l’écran. Un agent lit vingt fichiers, exécute la suite de tests et renvoie l’intégralité de 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. Chacun des trois outils comble 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 sa requête. Un analyseur de journaux les additionne et calcule leur prix.

ccusage est celui que la plupart des utilisateurs choisissent. Il ne nécessite aucune installation :

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

daily additionne les coûts par date. --breakdown sépare chaque ligne par modèle, ce qui permet de voir qu’un après-midi avec Opus représente la majeure partie de la semaine. blocks regroupe les coûts selon la fenêtre de cinq heures à laquelle un abonnement est réinitialisé. session additionne les coûts par conversation, et --instances les regroupe par projet afin d’identifier le dépôt le plus coûteux. Ajoutez --since et --until pour limiter la période, puis utilisez npx ccusage@latest daily --help pour connaître le format de date attendu par votre version. En août 2026, l’outil lit également les journaux 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 effectue le calcul à partir du nombre de tokens lorsqu’elle ne l’est pas. --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 écrit $0.00 pour les lignes qui n’en contiennent pas. 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é : toutes 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 ligne d’état. Consultez créer une statusline pour Claude Code pour le bloc de configuration et les champs qu’il reçoit.

Un analyseur de journaux ne peut pas voir ce qui ne s’est pas produit sur cette machine. Un deuxième ordinateur portable, une session sur claude.ai ou le travail d’un collègue : ces transcriptions se trouvent sur les disques correspondants. 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, de nature structurelle. La documentation d’Anthropic précise que le format des entrées est interne à Claude Code et qu’il change selon les versions. 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 pour vous, tandis que votre one-liner affichera un nombre faux avec assurance le jour où un champ sera renommé.

Enfin, le montant en dollars doit être nuancé dans le cas d’un abonnement. Avec Pro ou Max, vous n’êtes pas facturé par token. Ce nombre correspond donc à ce que vos tokens auraient coûté aux tarifs API publics. Il mesure l’intensité de votre utilisation. Il ne correspond pas à votre facture. Si la vraie question est de savoir quel forfait choisir, cette comparaison doit être menée séparément : consultez facturation API ou abonnement Claude.

Méthode 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 publics standard. Il ne tient pas compte des remises ni des tarifs promotionnels. Il peut donc différer de celui 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 aux serveurs MCP individuels, sous forme de pourcentage du total. Il signale les comportements représentant au moins 10% de l’utilisation récente, par exemple 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 deuxième appareil n’est donc pas comptabilisé. Lorsque cette barre est vide, et pas seulement faible, l’écran indique que la fenêtre est fermée, mais pas comment continuer à travailler. La marche à suivre après avoir atteint la limite dépend séparément du modèle, du contexte et du forfait.

Au-delà d’un seul développeur, 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 affichant les dépenses et les lignes acceptées pour chaque 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 informations visibles dépendent de la méthode de connexion de chaque développeur. Une organisation mixte doit donc consulter deux rapports et additionner les valeurs manuellement.

Pour dimensionner un budget, le chiffre publié dans la documentation tarifaire d’Anthropic en août 2026 correspond à 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 ce chiffre comme une référence publiée à partir de déploiements d’entreprise, et non comme une prévision pour votre équipe. Lancez un groupe pilote et mesurez les résultats avant toute extrapolation.

Les tableaux de bord ne peuvent pas descendre au niveau de la journée et de la personne. Ils vous indiqueront qu’Opus a représenté la majeure partie de l’utilisation mardi. Ils ne vous indiqueront pas quel prompt, quel dépôt ni quel job CI en est responsable. Ils accusent également un retard, car les rapports de l’organisation sont mis à jour quotidiennement. Ils servent donc à analyser l’utilisation, et non à détecter un agent qui s’emballe cet après-midi. Pour limiter un tel agent, il faut des limites, pas des rapports. C’est le sujet de la maîtrise des 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 peut être input, output, cacheRead ou cacheCreation, ainsi que model et query_source, qui peut être 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. C’est généralement le comportement du cache qui réserve les surprises. 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é. Son installation 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. Diriger OTEL_EXPORTER_OTLP_ENDPOINT vers Langfuse laisse donc le projet vide et ne produit aucune erreur exploitable. Langfuse est l’outil adapté 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 bon choix.

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

Deux services suffisent : un collector 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 découvre. É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 collector est ainsi accessible depuis vos machines, et depuis aucun autre endroit. L’adresse placée devant le port est importante ici, car les ports Docker publiés ne sont pas filtrés par ufw : voir pourquoi les ports Docker publiés contournent ufw. La configuration 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 collector 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

Le journal du collector doit se terminer par Everything is ready. Begin running and processing data.. Si le journal s’arrête sur une erreur de configuration, cela signifie que le YAML n’a pas pu être analysé et que le conteneur redémarrera 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 collector. 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 incohérence échoue silencieusement. Exécutez claude --debug ; le debug log indiquera 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 scrape sur http://localhost:9464/metrics. Lorsque prometheus est le seul exporter listé, Claude Code omet les unités USD, tokens et s des noms de métriques afin que le scrape reste au format texte Prometheus valide.

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

Suivi des dépenses pour les exécutions scriptées et CI

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

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

La charge utile 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 la valeur à un fichier ou envoyez-la comme métrique au collecteur précédent. C’est le suivi des dépenses utile le moins coûteux, et il nécessite un appel jq par exécution.

Modes de défaillance et symptômes observables

Le rapport est vide. npx ccusage@latest daily n’affiche aucune ligne : cela 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 affichent des totaux différents. C’est normal, et ce n’est pas un bug. /usage et tout parser de logs lisent uniquement l’historique local des sessions. L’utilisation depuis un autre appareil ou depuis claude.ai n’apparaît donc dans aucun des deux.

Le total local ne correspond pas à la facture. Les chiffres locaux sont calculés à partir du nombre de tokens, avec les tarifs catalogue standard. Ils ne tiennent pas compte 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 avez effectué le même travail. Vérifiez d’abord les colonnes relatives au cache. Une longue session renvoie l’intégralité de son historique à chaque tour. Le tarif du cache s’applique tant que le cache est disponible, puis le tarif complet des inputs s’applique lorsqu’il expire. Une longue interruption peut donc entraîner le retraitement de toute la conversation. Cela se traduit par un volume élevé d’inputs à côté d’un faible volume d’outputs. La tarification des tokens d’input et d’output 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 affichera le total, mais vous devrez en déduire la cause.

FAQ

ccusage indique-t-il le montant réellement facturé avec un forfait Max ?

Non. Avec un abonnement, la facturation ne se fait pas au token. Un parser de logs applique donc à vos tokens les 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 dû, consultez la page d’utilisation de la Console pour la facturation API et la page de facturation du forfait 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 documente le format des entrées comme interne et susceptible de changer selon les versions. 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, et non des spans. Les données ne peuvent donc pas être ingérées. Envoyez les métriques de Claude Code à un collecteur OpenTelemetry et stockez-les dans Prometheus. Utilisez Langfuse pour les agents que vous développez vous-même sur l’API, lorsque votre code émet des spans contenant le prompt, le modèle et le coût.

Pourquoi mes chiffres locaux ne correspondent-ils pas à la page d’utilisation de la Console ?

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

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'. La même charge utile contient une ventilation 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.