Suivi des coûts

Utilisez cette compétence pour analyser l'historique des coûts et de l'utilisation de Claude Code à partir du journal des métriques généré par le hook « stop:cost-tracker » d'ECC.

Emplacement des données

Le tracker ajoute un objet JSON par arrêt de session au fichier ~/.claude/metrics/costs.jsonl. Chaque ligne correspond à un instantané cumulatif pour cette session; pour calculer le total des dépenses, il faut donc prendre la dernière ligne par session_id et additionner les valeurs d’une session à l’autre — l’addition de chaque ligne entraîne un comptage multiple.

Schéma des lignes :

Privilégiez estimated_cost_usd plutôt que de calculer manuellement les prix : les prix des modèles et du cache varient, et le tracker fait autorité.

Quand l'utiliser

• L'utilisateur demande « Combien ai-je dépensé ? », « Combien a coûté cette session ? » ou « Quelle est ma consommation de jetons ? »
• L’utilisateur évoque des budgets, des limites de dépenses, des dépassements ou des contrôles de coûts.
• L’utilisateur souhaite une ventilation des coûts par modèle, session ou date, ou une exportation au format CSV.

Fonctionnement

Vérifiez d’abord que le journal existe (utilisez `node`, pas `sqlite3 ` — le tracker écrit en JSONL, et `node` est multiplateforme) :

node -e 'const fs=require("fs"),os=require("os"),p=require("path");const f=p.join(os.homedir(),".claude","metrics","costs.jsonl");console.log(fs.existsSync(f)?"journal des coûts trouvé":"journal des coûts introuvable : "+f)'

Si le journal est manquant, ne fabriquez pas de données d'utilisation. Indiquez à l'utilisateur que le suivi des coûts se remplit après la fin de la première session avec le hook `stop:cost-tracker` activé.

Exemple — résumé, par modèle, 7 derniers jours

node -e '
const fs=require("fs"),os=require("os"),path=require("path");
const f=path.join(os.homedir(),".claude","metrics","costs.jsonl");
if(!fs.existsSync(f)){console.log("journal des coûts introuvable : "+f);process.exit(0);}
const rows=fs.readFileSync(f,"utf8").split(/\r?\n/).filter(Boolean).map(l=>{try{return JSON.parse(l)}catch{return null}}).filter(Boolean);
const bySession = new Map();
for (const r of rows) { const k = r.session_id || r.transcript_path || r.timestamp; const p = bySession.get(k); if (!p || String(r.timestamp)>String(p.timestamp)), bySession.set(k, r);}
const latest = [...bySession.values()];
const cost = r => Number(r.estimated_cost_usd) || 0, day = r => String(r.timestamp || "").slice(0, 10), sum = a => a.reduce((s, r) => s + cost(r), 0), f4 = n => "$" + n.toFixed(4);
const today = new Date().toISOString().slice(0, 10), yest = new Date(Date.now() - 864e5).toISOString().slice(0, 10);
console.log("aujourd’hui : "+f4(sum(latest.filter(r=>day(r)===today)))+" | hier : " + f4(sum(latest.filter(r => day(r) === yest))) + " | total : " + f4(sum(latest)) + " (" + latest.length + " sessions)");
const m = new Map(); for (const r of latest) { const k = r.model || "(unknown)"; m.set(k, (m.get(k) || 0) + cost(r)); }
console.log("par modèle :"); [...m.entries()].sort((a, b) => b[1] - a[1]).forEach(([k, v]) => console.log("  " + f4(v) + "  " + k));
'

Pour une analyse détaillée d’une session ou une exportation au format CSV, parcourez le même ensemble « latest » (ou les lignes brutes pour le CSV) et affichez les champs dont vous avez besoin.

Conseils pour les rapports

Lors de la présentation des données de coûts, incluez les dépenses d’aujourd’hui par rapport à celles d’hier, le total sur l’ensemble des sessions, une ventilation par modèle et le nombre de sessions. Affichez les montants inférieurs à un dollar avec quatre décimales, et les montants plus importants avec deux.

Anti-modèles

• Ne totalisez pas chaque ligne — les montants sont cumulés par session ; réduisez d’abord le tout à la dernière ligne par session_id.
• N’estimez pas les coûts à partir du nombre brut de jetons lorsque le champ ` estimated_cost_usd ` est présent.
• Ne partez pas du principe que le journal existe sans avoir vérifié.
• Ne codez pas en dur les tarifs actuels des modèles dans les réponses destinées aux utilisateurs.
• Ne recommandez pas l’installation de hooks ou de plugins non vérifiés qui exécutent du code arbitraire.

Connexes

• /cost-report - Rapport sous forme de commande portant sur le même journal de métriques.
• cost-aware-llm-pipeline - Modèles de routage des modèles et de conception budgétaire.
• token-budget-advisor - Planification du contexte et du budget de tokens.
• strategic-compact - Compactage du contexte pour réduire la dépense répétée de jetons.