Agent skill · data analytics · affaan-m
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.
Why this skill is useful
Provides specific commands and logic for analyzing cost data from the Claude Code metrics log that the AI wouldn't reliably generate on its own.
What it needs
Requires node installed locally. About 3k tokens when loaded. Last updated 2026-08-06. 238,342 stars on the source repository.
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 sessionid 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 sessionid Claude Code session identifier transcriptpath Path to the session transcript model Model used inputtokens / outputtokens Token counts cachewritetokens / cachereadtokens Prompt-cache token counts estimatedcostusd Precomputed cumulative cost in USD for the session Prefer estimatedcostusd 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): If the log is missing, do not fabricate usage data. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills affaan-m/cost-tracking--5e85c5