cost-tracking

SKILL.md

Cost Tracking

Use this skill to analyze Claude Code cost and usage history from the metrics log
that ECC's stop:cost-tracker hook writes.

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.

Row schema:

Field
Meaning

timestamp
ISO timestamp of the snapshot

session_id
Claude Code session identifier

transcript_path
Path to the session transcript

model
Model used

input_tokens / output_tokens
Token counts

cache_write_tokens / cache_read_tokens
Prompt-cache token counts

estimated_cost_usd
Precomputed cumulative cost in USD for the session

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

When to Use

The user asks "how much have I spent?", "what did this session cost?", or
"what is my token usage?"

The user mentions budgets, spending limits, overruns, or cost controls.

The user wants a cost breakdown by model, session, or date, or a CSV export.

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.