Suivi des coûts
Utilisez cette compétence pour analyser l'historique des coûts et de l'utilisation de Claude Code à partir du fichier journal des métriques que le hook stop:cost-tracker d'ECC écrit.
Où se trouvent les données
L'outil de suivi ajoute un objet JSON par session terminée dans ~/.claude/metrics/costs.jsonl. Chaque ligne est un instantané cumulatif pour cette session, donc pour obtenir le total des dépenses, prenez la dernière ligne par session_id et additionnez les sessions — additionner chaque ligne reviendrait à compter plusieurs fois.
Schéma des lignes :
| Champ | Signification |
|---|---|
timestamp | Horodatage ISO de l'instantané |
session_id | Identifiant de session Claude Code |
transcript_path | Chemin vers la transcription de la session |
model | Modèle utilisé |
input_tokens / output_tokens | Nombre de jetons |
cache_write_tokens / cache_read_tokens | Jetons du cache de prompt |
estimated_cost_usd | Coût cumulatif précalculé en USD pour la session |
Préférez estimated_cost_usd au calcul manuel des prix — les prix des modèles et du cache changent, et l'outil de suivi est la source de vérité.
Quand l'utiliser
- L'utilisateur demande « combien ai-je dépensé ? », « combien a coûté cette session ? » ou « quelle est mon utilisation de jetons ? »
- L'utilisateur mentionne des budgets, des limites de dépenses, des dépassements ou des contrôles de coûts.
- L'utilisateur souhaite une répartition des coûts par modèle, session ou date, ou une exportation CSV.
Comment ça fonctionne
Vérifiez d'abord que le journal existe (utilisez node, pas sqlite3 — l'outil de suivi écrit du 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)?"fichier de coûts trouvé":"fichier de coûts introuvable : "+f)'
Si le journal est manquant, ne fabriquez pas de données d'utilisation. Dites à l'utilisateur que le suivi des coûts se remplit après la première session terminée 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("fichier de 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||"(inconnu)";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 exploration détaillée d'une session ou une exportation CSV, parcourez le même ensemble latest (ou les lignes brutes pour CSV) et affichez les champs nécessaires.
Recommandations pour les rapports
Lorsque vous présentez des données de coûts, incluez les dépenses d'aujourd'hui par rapport à hier, le total de toutes les sessions, une répartition par modèle et le nombre de sessions. Formatez les montants inférieurs à un dollar avec quatre décimales, les montants plus importants avec deux.
Anti-patrons
- N'additionnez pas chaque ligne — elles sont cumulatives par session ; réduisez d'abord à la dernière ligne par
session_id. - N'estimez pas les coûts à partir des nombres bruts de jetons lorsque
estimated_cost_usdest présent. - Ne supposez pas que le journal existe sans vérifier.
- Ne codez pas en dur les tarifs actuels des modèles dans les réponses destinées aux utilisateurs.
- Ne recommandez pas d'installer des hooks ou plugins non vérifiés qui exécutent du code arbitraire.
Liens connexes
/cost-report- Rapport en ligne de commande sur le même fichier de métriques.cost-aware-llm-pipeline- Routage de modèles et schémas de conception budgétaire.token-budget-advisor- Planification du contexte et du budget de jetons.strategic-compact- Compactage du contexte pour réduire les dépenses répétées en jetons.