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 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. Il ne s’agissait pas de trois versions du même outil, et c’est ce qui est intéressant. L’un analysait les fichiers de session locaux. Le deuxième encapsulait les écrans d’utilisation du compte. Le troisième était un backend de tracing 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 est devenu difficile à prévoir. Le coût d’une conversation correspond à 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 d’un contexte que vous n’avez jamais saisi. Avec un abonnement, le montant en dollars affiché par Claude Code pour la session est une estimation qu’Anthropic indique comme non pertinente pour la facturation. Le chiffre important est une barre d’utilisation qui se vide plus ou moins vite selon les jours. Ces trois outils couvrent chacun une partie différente de ce manque d’information.

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, avec les caractères non alphanumériques 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 les additionne 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 totalise les coûts par date. --breakdown sépare chaque ligne par modèle. Cela 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 au terme de laquelle l’abonnement est réinitialisé. session calcule les totaux par conversation, et daily --instances les regroupe par projet pour 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 octobre 2026, l’outil lit également les données d’autres CLI d’agents, notamment Codex et OpenCode. Cela est utile pour les comparer.

Les coûts proviennent d’une table de prix des modèles, et l’outil propose trois modes de calcul. --mode auto utilise la valeur costUSD enregistrée par Claude Code dans le fichier lorsqu’elle est présente, et calcule le coût à partir du nombre 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 pas. Si un total semble incorrect, exécutez le même rapport avec calculate, puis avec display. Un écart important entre les deux signifie que la plupart des entrées ne contiennent aucun coût enregistré. Les valeurs affichées sont donc des estimations. Si vous bénéficiez de tarifs négociés, pricingOverrides sous defaults dans un fichier de configuration ccusage.json remplace le prix des modèles individuels.

Les mêmes données peuvent alimenter votre prompt. ccusage statusline affiche une ligne compacte pour la barre d’état de Claude Code. Vous pouvez l’intégrer à ~/.claude/settings.json comme toute autre commande de ligne d’état. Consultez créer une ligne d’état Claude Code pour connaître 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. Les sessions ouvertes sur un deuxième ordinateur portable, sur claude.ai ou par un collègue sont stockées 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, sauf si vous les avez archivées.

Il existe un autre risque, lié à la structure des fichiers. 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 nouvelle version. Cela s’applique à tous les outils de ce type. C’est également pourquoi un simple 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, tandis que votre one-liner affichera un nombre 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. L’utilisation comprise dans la limite de votre offre Pro ou Max n’est pas facturée par token. Le montant indique donc ce que vos tokens auraient coûté aux tarifs API publics. Il mesure l’intensité de votre utilisation. Ce n’est pas votre facture. Les crédits d’utilisation constituent une exception : si vous les activez, l’utilisation au-delà de la limite de l’offre est facturée aux tarifs API standard, sous la forme d’un débit distinct. claude.ai affiche le montant du mois dans Settings > Usage. Si vous cherchez réellement à déterminer quelle offre choisir, cette comparaison doit être traitée séparément : consultez facturation API et abonnement Claude.

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

Claude Code fournit ses propres rapports, mais la plupart des utilisateurs ne les ouvrent 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, sauf si un administrateur a défini une table modelPricing dans les paramètres gérés. Dans ce cas, la ligne Total cost indique at your organization's configured rates. Dans tous les cas, ce montant est une estimation qui peut différer de votre facture. Avec les offres Pro ou Max, Anthropic précise qu’il n’est pas pertinent pour la facturation, car cette utilisation est incluse dans l’offre. Les totaux sont réinitialisés lorsque /clear démarre une nouvelle conversation.

Avec une offre Pro, Max, Team ou Enterprise basée sur des sièges, le même écran indique la part de la limite de votre offre que vous avez utilisée. L’offre Enterprise basée sur l’utilisation ne comporte pas de quota inclus à épuiser, car chaque token est facturé aux tarifs de l’API. Avec ces offres, l’écran attribue également l’utilisation récente aux skills, subagents, plugins et serveurs MCP individuels, sous forme de pourcentage du total. Il signale les comportements qui représentent au moins 10% de l’utilisation récente, par exemple un contexte long ou des cache misses. Appuyez sur d ou w pour passer des dernières 24 heures aux 7 derniers jours. Ces chiffres sont approximatifs et 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 plutôt que simplement faible, l’écran indique que la fenêtre est fermée, mais pas comment continuer à travailler. Que faire après avoir atteint la limite est une décision distincte concernant le modèle, le contexte et l’offre.

Au-delà d’un seul développeur, les chiffres passent au niveau du 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 offres Team et Enterprise fournissent un rapport des dépenses dans la console d’administration, avec export CSV et mise à jour quotidienne. Ce rapport couvre toutefois les dépenses en usage credits : l’utilisation comprise dans le quota de sièges n’est pas mesurée en dollars. Enterprise ajoute une API d’analytics. Les éléments visibles dépendent de la méthode utilisée par chaque développeur pour se connecter. Une organisation mixte 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 octobre 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 cette valeur 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 l’utilisation avant de faire une extrapolation.

Les tableaux de bord ne peuvent pas voir ce qui se situe à un niveau plus fin que le jour et la personne. Ils vous indiqueront qu’Opus a représenté la majeure partie de l’utilisation du mardi. Ils ne vous indiqueront pas quelle invite, quel dépôt ou quel job CI en est responsable. Ils présentent également un décalage, car les rapports d’organisation sont mis à jour quotidiennement. Ils servent donc à analyser l’utilisation, et non à détecter dans l’après-midi un agent qui consomme excessivement des ressources. Pour arrêter ce type de dérive, 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 en temps quasi réel les données de tokens et de coûts par utilisateur vers un système que vous contrôlez. 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. Les noms des serveurs MCP que vous avez configurés vous-même et de vos propres sous-agents personnalisés sont transmis sous la forme custom, sauf si vous définissez OTEL_LOG_TOOL_DETAILS=1. Cette option ajoute également les commandes Bash et les entrées des outils aux événements d’outils. Cela suffit pour répondre à des questions qu’aucun dashboard ne peut traiter : quelle part de la facture provient des sous-agents plutôt que de 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. Le comportement du cache réserve généralement les surprises, 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. Par défaut, Claude Code exporte des métriques et des événements de journalisation, mais pas de spans. Diriger OTEL_EXPORTER_OTLP_ENDPOINT vers Langfuse laisse donc le projet vide et ne produit aucune erreur exploitable. L’export des spans existe bien, mais il reste désactivé en version bêta tant que vous ne définissez pas CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 et OTEL_TRACES_EXPORTER. L’intégration Claude Code de Langfuse utilise une autre méthode : un hook Stop, ou un plugin qui en installe un, lit les transcriptions des sessions après chaque réponse et les convertit en traces. Elle est donc soumise aux mêmes limites locales qu’un analyseur de journaux. 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 obtenir les totaux de dépenses de la CLI Claude Code, un système de stockage de métriques est mieux 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 nulle part ailleurs. L’adresse placée devant le port joue ici un rôle important, 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 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

Le journal du collecteur doit se terminer par Everything is ready. Begin running and processing data.. Un journal qui s’arrête sur une erreur de configuration indique que le YAML n’a pas pu être analysé. Le conteneur redémarrera alors 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 reçu :

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

Vous devriez obtenir plusieurs noms qui commencent 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 incohérence échoue sans message explicite. Exécutez claude --debug-file /tmp/claude-debug.log et recherchez dans ce fichier les lignes [3P telemetry]. Claude Code y signale 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 à http://localhost:9464/metrics. Lorsque prometheus est le seul exporter listé, Claude Code omet les unités USD, tokens et s des métriques exportées. Le scraping reste ainsi conforme au format texte Prometheus. Les noms des métriques ne changent pas. Un paramètre qui combine plusieurs exporters, comme otlp,prometheus, conserve les unités.

Cette architecture implique un choix en matière de confidentialité. Par défaut, seuls les compteurs et les métadonnées quittent la machine. Le texte des prompts et la sortie des outils ne sont pas exportés. OTEL_LOG_USER_PROMPTS=1 ajoute le texte des prompts aux événements exportés et OTEL_LOG_TOOL_CONTENT=1 ajoute la sortie des outils aux trace spans. Dès que vous exportez l’un de ces signaux, votre serveur de télémétrie contient du code source et tout ce qui se trouvait dans le contexte. Activez ces options délibérément et lisez d’abord éviter les secrets dans le contexte de l’agent.

Suivre les dépenses des 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 tableau de bord. Comme toute valeur locale, il s’agit d’une estimation côté client. Une exécution qui poursuit une conversation avec --continue ou --resume indique le total de la conversation, y compris les exécutions précédentes. Ajoutez cette valeur à un fichier ou envoyez-la comme métrique au collecteur indiqué plus haut. C’est le moyen le moins coûteux de suivre utilement les dépenses, et il nécessite un appel à jq par exécution.

Modes d’échec et symptômes 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 à l’analyseur. Si des lignes sont présentes, mais s’arrêtent environ un mois auparavant, c’est le fonctionnement prévu de cleanupPeriodDays : les transcriptions sont supprimées après 30 jours par défaut.

Deux machines indiquent des totaux différents. C’est normal, et ce n’est pas un bug. Le détail de /usage et tout analyseur de journaux ne lisent que l’historique des sessions locales. L’utilisation depuis un autre appareil ou depuis claude.ai est donc absente des deux rapports.

Le total local ne correspond pas à la facture. Les montants locaux sont calculés à partir du nombre de tokens et des tarifs catalogue standard, sauf si vous configurez des tarifs contractuels : une table modelPricing dans les paramètres administrés pour /usage, ou pricingOverrides pour ccusage. Avec un abonnement, l’utilisation comprise dans la limite du forfait n’est pas facturée au token. Seuls les crédits d’utilisation le sont. 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 du cache. Une longue session renvoie tout son historique à chaque tour. Les données sont facturées au tarif du cache tant que celui-ci est chaud, puis au tarif complet des entrées lorsqu’il expire. Une longue interruption peut donc entraîner 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 faible 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 sous-agents semble impossible. Chaque sous-agent utilise sa propre fenêtre de contexte. La consommation de tokens dépend donc du nombre de sous-agents exécutés et de la durée de chacun. Avec un forfait, l’attribution /usage indique la part des sous-agents pour cette machine, sous forme de pourcentage. Pour le détail par requête, les données OTel les distinguent grâce à l’attribut query_source sur claude_code.token.usage. Un analyseur de journaux vous montrera le total, mais vous devrez en déduire la répartition.

FAQ

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

Non. L’utilisation comprise dans la limite d’un forfait n’est pas facturée par token. Un parseur de logs valorise donc vos tokens aux tarifs catalogue standard de l’API 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. Pour connaître le montant dû, consultez la page d’utilisation de la Console pour la facturation de l’API et la page de facturation du forfait pour un abonnement. Si les crédits d’utilisation sont activés, l’utilisation au-delà de la limite est facturée aux tarifs API standard. claude.ai affiche alors cette dépense dans Settings > Usage.

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

Dans ~/.claude/projects/<project>/<session-id>.jsonl. <project> correspond au chemin du répertoire de travail, dont les caractères non alphanumériques sont 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. 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 pour l’analyser plutôt que votre propre script.

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

Pas avec la télémétrie par défaut. Le endpoint OTLP de Langfuse accepte les traces. Par défaut, Claude Code exporte toutefois des métriques et des événements de logs, et non des spans. Ces données n’ont donc pas de destination. L’export des spans est une fonctionnalité beta qu’il faut activer. L’intégration Claude Code de Langfuse utilise plutôt un hook Stop qui convertit les transcriptions de session en traces. Pour les totaux de dépenses, 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. Votre code peut 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 parseurs de logs additionnent les nombres de tokens des fichiers de session présents sur la machine que vous utilisez. Ils appliquent ensuite les tarifs catalogue standard, sauf si des tarifs négociés sont configurés via modelPricing dans les paramètres gérés pour /usage ou via pricingOverrides pour ccusage. La Console indique le montant réellement facturé à votre organisation, sur toutes les machines et avec toutes les clés, après application des remises éventuelles. Un écart est normal. Un écart très important indique généralement qu’un second appareil, un runner CI ou un autre membre de l’équipe utilise le même compte pour la facturation.

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

Exécutez-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 le détail par modèle et l’ID de session. Enregistrez cette valeur pour chaque job. Vous obtiendrez ainsi la dépense par pipeline, sans agent, dashboard ni service supplémentaire.