CodeBurn — stats de tokens et coûts pour Claude Code & agents IA

1📖 Glossaire — le vocabulaire de base

• Token — unité de facturation des LLM (~0,75 mot en anglais) ; on paie les tokens d'entrée (input), de sortie (output) et de cache.
• Cache read / cache write — le prompt caching d'Anthropic permet de relire un préfixe de prompt déjà envoyé pour ~10% du prix ; l'écriture en cache coûte ~25% plus cher qu'un input normal. Le taux de cache hit est LE levier n°1 du coût réel.
• Burn rate — vitesse à laquelle on consomme des tokens (et donc de l'argent) par unité de temps.
• JSONL — format « JSON Lines » : un objet JSON par ligne, append-only. C'est le format des transcripts de Claude Code.
• TUI — Terminal User Interface : interface interactive dans le terminal (dashboard navigable au clavier).
• One-shot rate — proportion de modifications réussies du premier coup, sans cycle de retry sur le même fichier.

2Ce que fait CodeBurn — vue d'ensemble

CodeBurn est un outil gratuit, open source (MIT), 100% local qui répond à la question : « où part mon argent IA ? » Il agrège la consommation de 36 outils (Claude Code, Cursor, Codex, Gemini CLI, Copilot, Zed, Warp, OpenCode…) et la ventile par modèle, par projet et par tâche.

Lancement immédiat, sans installation :

npx codeburn

Ce qu'on obtient :

• Coût total et par période (jour, semaine, mois, lifetime), converti dans 162 devises (taux BCE quotidiens)
• Ventilation par modèle : Opus vs Sonnet vs Haiku, avec coût par appel, tokens de sortie par appel, taux de cache hit
• Ventilation par projet : quel repo brûle le plus
• Ventilation par activité : 13 catégories (Coding, Debugging, Feature Dev, Refactoring, Testing, Exploration, Planning, Delegation, Git Ops, Build/Deploy, Brainstorming, Conversation, General)

3Comment ça marche sous le capot

Chaque outil IA stocke ses sessions dans un format et un emplacement qui lui sont propres. CodeBurn connaît ces emplacements et les parse directement :

Les variables d'environnement CLAUDE_CONFIG_DIR, CODEX_HOME, OPENCODE_DATA_DIR permettent d'overrider les chemins par défaut.

flowchart LR
    subgraph Sources["📁 Fichiers déjà sur disque"]
        CC["Claude Code<br/>*.jsonl"]
        CX["Codex<br/>rollout-*.jsonl"]
        CU["Cursor<br/>state.vscdb"]
        GM["Gemini CLI<br/>session-*.json"]
    end
    P["Parser<br/>+ dédup par API ID<br/>+ filtre par dates"]
    K["Classification<br/>13 catégories d'activité<br/>(patterns d'outils + mots-clés)"]
    PR["Pricing LiteLLM<br/>input · output · cache r/w<br/>· web search · fast mode"]
    subgraph Surfaces["🖥️ 4 surfaces"]
        TUI["TUI — npx codeburn"]
        WEB["Web — localhost:4747"]
        DESK["App desktop"]
        BAR["Menubar macOS"]
    end
    CC --> P
    CX --> P
    CU --> P
    GM --> P
    P --> K --> PR
    PR --> TUI
    PR --> WEB
    PR --> DESK
    PR --> BAR

Trois étapes clés du pipeline :

1. Déduplication par API ID — un même message peut apparaître plusieurs fois dans les transcripts (resume de session, retries) ; sans dédup, les coûts seraient surestimés.
2. Classification déterministe — les 13 catégories d'activité sont déduites des patterns d'usage d'outils et des mots-clés des messages utilisateur, sans aucun appel LLM. L'analyse est donc gratuite, rapide et reproductible.
3. Pricing — chaque appel API est valorisé avec les compteurs input, output, cache read, cache write et web search, via les tarifs LiteLLM (rafraîchis quotidiennement, cachés 24h dans ~/.cache/codeburn/), avec un multiplicateur pour le fast mode de Claude.

4Les 4 surfaces — une seule source de vérité

Même moteur d'analyse, quatre façons de le consulter :

Installation durable si le npx ponctuel ne suffit plus :

npm install -g codeburn   # CLI globale (Node.js >= 22.13)
brew install codeburn     # macOS

5Les commandes essentielles

# Dashboards & rapports
npx codeburn                       # dashboard interactif (7 derniers jours)
codeburn today                     # aujourd'hui
codeburn month                     # mois en cours
codeburn overview                  # résumé mensuel copy-pasteable
codeburn report --format json      # sortie structurée pour scripts

# Filtres
codeburn report -p 30days                    # période : today|week|30days|month|all
codeburn report --provider claude-code       # un seul outil
codeburn report --project shard              # un seul projet
codeburn report --from 2026-07-01 --to 2026-07-31

# Breakdown par modèle
codeburn models --by-task          # quel modèle pour quel type de tâche
codeburn export -f json            # export CSV/JSON

# Diagnostic
codeburn doctor                    # vérifie la détection de chaque provider
codeburn audit                     # table des sources de tokens par provider
codeburn context <id>              # explorateur de context window d'une session

6Les analyses avancées — là où CodeBurn se démarque

codeburn optimize — détection de gaspillage

Scanne les 30 derniers jours à la recherche de patterns de waste, chacun avec une estimation d'économie en tokens et en dollars :

• fichiers relus plusieurs fois dans une même session
• ratio lecture/édition trop faible (beaucoup de lecture, peu de production)
• sorties bash non plafonnées qui inondent le contexte
• serveurs MCP connectés mais jamais utilisés (leurs schémas d'outils coûtent des tokens à chaque tour !)
• agents fantômes, fichiers de config obèses (CLAUDE.md trop long), sessions à contexte lourd
• sessions chères à faible valeur

codeburn optimize            # scan et rapport
codeburn optimize --apply    # applique les fixes de façon interactive
codeburn act list|undo       # historique des changements + rollback

codeburn compare — quel modèle est vraiment rentable ?

Comparaison côte à côte : one-shot rate, taux de retry, auto-correction, coût par appel, coût par édition, tokens de sortie par appel, cache hit rate. Un retry est détecté quand le même fichier est ré-édité après une commande shell intercalée — c'est-à-dire un cycle « édite → teste → échoue → ré-édite ». Un modèle moins cher au token mais qui retry deux fois plus peut coûter plus cher au résultat.

codeburn yield — le spend a-t-il produit quelque chose ?

Corrèle les sessions avec les commits git par timestamp et classe chaque dollar dépensé en : Productive (le code a été commité), Reverted (commité puis annulé), Abandoned (jamais commité) ou Ambiguous. C'est la seule métrique qui répond à « est-ce que ces 40$ ont servi à quelque chose ? ».

7Budget Guard — le garde-fou par hooks

codeburn guard install installe des hooks dans les settings de Claude Code qui surveillent le spend de la session en temps réel, avec trois seuils configurables : checkpoint (3$ par défaut), soft cap (5$) et hard cap (15$).

sequenceDiagram
    participant Dev as Développeur
    participant CC as Claude Code
    participant G as Hook CodeBurn (guard)
    Dev->>CC: prompt
    CC->>G: hook déclenché
    G->>G: calcule le spend de la session
    alt spend < soft cap (5$)
        G-->>CC: ✓ rien à signaler
    else soft cap dépassé
        G-->>CC: ⚠️ avertissement affiché au dev
    else hard cap dépassé (15$)
        G-->>CC: ⛔ la session est bloquée
    end
    CC-->>Dev: réponse (ou blocage)

codeburn guard install    # installe les hooks
codeburn guard status     # état des caps

8Intégration MCP — interroger ses stats depuis Claude

CodeBurn expose ses données via un serveur MCP (Model Context Protocol — le protocole standard pour connecter des outils aux LLM) local :

claude mcp add codeburn -- npx -y codeburn mcp

Deux outils sont exposés : get_usage et get_savings. On peut donc demander à Claude Code lui-même « combien ai-je dépensé cette semaine et sur quoi ? » — l'agent devient capable d'introspecter son propre coût.

9Tableau de synthèse — CodeBurn vs les alternatives

Quand choisir CodeBurn : dès qu'on utilise plusieurs outils IA, qu'on veut comprendre où partent les tokens (pas juste combien), ou qu'on veut une boucle d'optimisation actionnable. Quand préférer ccburn/Usage Monitor : si le besoin est uniquement de surveiller en temps réel la proximité des limites d'un abonnement Claude.

Sources

• github.com/getagentseal/codeburn — repo officiel : README complet, commandes, sources de données par provider
• codeburn.app — site officiel de l'outil
• Recommandation CodeBurn — awesome-claude-code #1549 — présentation de l'outil dans la liste awesome-claude-code
• Claude Code Stats : /stats, codeburn, ccusage (Medium) — comparatif des outils de stats pour Claude Code
• github.com/JuanjoFuchs/ccburn — alternative focalisée sur les limites d'abonnement (burn-up charts)
• github.com/Maciek-roboblog/Claude-Code-Usage-Monitor — alternative monitoring temps réel avec prédictions