Cost Tracking

Where the data lives

The tracker appends one JSON object per session-stop to ~/.claude/metrics/costs.jsonl. Each row is a cumulative snapshot for that session, so to total spend you take the latest row per session_id and sum across sessions — summing every row multiply-counts.

ECC also maintains internal per-session files under ~/.claude/metrics/cost-snapshots/ so runtime hooks can read the current session total without rescanning all history. Treat those files as a rebuildable cache; each snapshot stores a byte cursor so only newly appended rows are scanned. Stable reads are O(1), while updates are O(new bytes). Stale entries are pruned after 30 days or when the directory exceeds 512 sessions. Cold catch-up work is limited to 16 MiB per hook invocation, and malformed unterminated rows larger than 1 MiB are discarded with a resumable cursor. Reports and exports should continue to use costs.jsonl.

Row schema:

Prefer estimated_cost_usd over hand-calculating pricing — model and cache prices change, and the tracker is the source of truth.

How It Works

First verify the log exists (use node, not sqlite3 — the tracker writes JSONL, and node is cross-platform):

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)?"cost log found":"cost log not found: "+f)'

If the log is missing, do not fabricate usage data. Tell the user that cost tracking populates after the first session ends with the stop:cost-tracker hook enabled.

Example — summary, by model, last 7 days

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("cost log not found: "+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("today: "+f4(sum(latest.filter(r=>day(r)===today)))+" | yesterday: "+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("by model:");[...m.entries()].sort((a,b)=>b[1]-a[1]).forEach(([k,v])=>console.log("  "+f4(v)+"  "+k));
'

For a session drilldown or CSV export, iterate the same latest set (or the raw rows for CSV) and print the fields you need.

Reporting Guidance

When presenting cost data, include today's spend vs yesterday, total across all sessions, a by-model breakdown, and session count. Format sub-dollar amounts with four decimals, larger amounts with two.

Anti-Patterns

• Do not sum every row — they are cumulative per session; reduce to the latest row per session_id first.
• Do not estimate costs from raw token counts when estimated_cost_usd is present.
• Do not assume the log exists without checking.
• Do not hard-code current model pricing in user-facing answers.
• Do not recommend installing unreviewed hooks or plugins that execute arbitrary code.

Related

• /cost-report - Command-form report over the same metrics log.
• cost-aware-llm-pipeline - Model-routing and budget-design patterns.
• token-budget-advisor - Context and token-budget planning.
• strategic-compact - Context compaction to reduce repeated token spend.