Cost Tracking
Track and report Claude Code token usage, spending, and budgets from the local ECC cost-tracker metrics log. Use when the user asks about costs, spending, usage, tokens, budgets, or cost breakdowns by model, session, or date.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Cost Tracking when an AI agent needs a reusable SKILL.md workflow for this job: Track and report Claude Code token usage, spending, and budgets from the local ECC cost-tracker metrics log. Use when the user asks about costs, spending, usage, tokens, budgets, or cost breakdowns by model, session, or date.
When not to use it
Skip Cost Tracking when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/cost-tracking # Save SKILL.md to ~/.claude/skills/cost-tracking/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/cost-tracking/SKILL.md. For a shared project, commit the folder at .claude/skills/cost-tracking/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Cost Tracking skill for this task: The user asks "how much have I spent?", "what did this session cost?", or. Confirm any required inputs or files before making changes.
What supports this recommendation?
81/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 87/100
- Practical detail
- 92/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- geminiinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- copilotinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- llamainferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- perplexityinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- mistralinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- grokinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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.
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:
| 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):
```bash 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
```bash 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.
Intended uses
- The user asks "how much have I spent?", "what did this session cost?", or
- 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.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.