Suivi des coûts

Que fait 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 que le hook stop:cost-tracker d'ECC écrit.

Où se trouvent les données

Le tracker 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, vous prenez la dernière ligne par session_id et additionnez les sessions — additionner chaque ligne compterait 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 le transcript de la session
model	Modèle utilisé
input_tokens / output_tokens	Compteurs de tokens
cache_write_tokens / cache_read_tokens	Compteurs de tokens de cache de prompt
estimated_cost_usd	Coût cumulatif précalculé en USD pour la session

Préférez estimated_cost_usd plutôt qu'un calcul manuel des prix — les prix des modèles et du cache changent, et le tracker est la source de vérité.

Quand utiliser

• L'utilisateur demande « combien ai-je dépensé ? », « combien a coûté cette session ? » ou « quelle est ma consommation de tokens ? »
• 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 un export CSV.

Comment ça fonctionne

Vérifiez d'abord l'existence du journal (utilisez node, pas sqlite3 — le tracker é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)?"journal des coûts trouvé":"journal des coûts introuvable : "+f)'

Si le journal est manquant, n'inventez pas de données d'utilisation. Dites à l'utilisateur que le suivi des coûts se peuple 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||"(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 un détail par session ou un export CSV, parcourez le même ensemble latest (ou les lignes brutes pour CSV) et imprimez les champs nécessaires.

Directives de rapport

Lors de la présentation des données de coûts, incluez les dépenses d'aujourd'hui par rapport à hier, le total sur 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 compteurs bruts de tokens lorsque estimated_cost_usd est présent.
• Ne présumez pas que le journal existe sans vérification.
• Ne codez pas en dur les prix actuels des modèles dans les réponses destinées à l'utilisateur.
• Ne recommandez pas l'installation de hooks ou plugins non vérifiés qui exécutent du code arbitraire.

Liens connexes

• /cost-report - Rapport en ligne de commande basé sur le même journal de métriques.
• cost-aware-llm-pipeline - Routage de modèles et conception de budgets.
• token-budget-advisor - Planification du contexte et du budget de tokens.
• strategic-compact - Compactage du contexte pour réduire les dépenses répétées en tokens.