# cost-tracking

> A Claude Code skill from Affaan M's everything-claude-code repo that reads a local SQLite usage database (~/.claude-cost-tracker/usage.db) written by an existing cost-tracking hook, then runs SQL summaries — today's spend, top projects, top tools, last-7-days trend, per-session drilldown — without re-pricing tokens by hand.

**Use case**: Answer cost / usage / budget questions from a local SQLite database instead of fabricating estimates from token math

**Canonical URL**: https://agentcookbooks.com/skills/cost-tracking/

**Topics**: claude-code, skills, cost-management

**Trigger phrases**: "how much have I spent on Claude Code", "cost breakdown by project this week", "what did this session cost"

**Source**: [Affaan M](https://github.com/affaan-m/everything-claude-code/tree/main/skills/cost-tracking)

**License**: MIT

---

## What it does

`cost-tracking` is the spend-reporting skill in [Affaan M's everything-claude-code](https://github.com/affaan-m/everything-claude-code) — see [skills/cost-tracking](https://github.com/affaan-m/everything-claude-code/tree/main/skills/cost-tracking). It analyzes Claude Code cost and usage from a local SQLite database (`~/.claude-cost-tracker/usage.db`) that an existing cost-tracking hook or plugin writes to — the skill itself is read-only and assumes the tracker is the source of truth for how each row was priced.

The skill ships five SQL recipes against a canonical `usage` table schema (`timestamp`, `project`, `tool_name`, `input_tokens`, `output_tokens`, `cost_usd`, `session_id`, `model`): a quick summary line (today / total / calls / sessions), cost by project, cost by tool, last-7-days trend, and a session drilldown that ranks the last ten sessions by start time. Every recipe rounds via `ROUND(SUM(cost_usd), 4)` and prefers `cost_usd` over recomputing from raw token counts — model prices change, and hand-calculating defeats the tracker.

A prerequisite-check block runs first: `command -v sqlite3` and `test -f ~/.claude-cost-tracker/usage.db`. If either fails, the skill is explicit that it must not fabricate usage data — it tells the user cost tracking isn't configured and suggests installing a trusted local hook rather than guessing. The reporting-guidance section enforces a consistent output shape: today's spend, yesterday comparison, total, top projects, top tools, sessions count + average per session.

## When to use it

- Operator asks "how much have I spent this week?" and an existing tracker has been writing rows to the database
- Comparing today against yesterday or surfacing a 7-day trend for a budget-review conversation
- Breaking spend down by project or tool to find the heaviest consumers
- Drilling into a recent session to see start, end, total cost, and call count
- Exporting recent usage records as CSV for an external dashboard

When *not* to reach for it:

- No cost tracker is installed and the database doesn't exist — the skill correctly refuses to fabricate
- Pricing model strategy or model-routing decisions — those belong to `token-budget-advisor` or a cost-aware pipeline skill
- Compaction strategy to reduce future spend — that's `strategic-compact`

## Install

From [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) at `skills/cost-tracking/`. Drop the folder into `~/.claude/skills/cost-tracking/`. The skill itself is markdown but requires `sqlite3` on PATH and a populated `~/.claude-cost-tracker/usage.db`. The database is *not* shipped by this skill — it's written by a separate cost-tracking hook or plugin (the original tracker came from a stale community PR; the skill is the salvaged reporting half). Without the hook running, the prerequisite checks fail and the skill refuses to invent numbers.

## What a session looks like

1. **User asks the cost question.** "What did this week cost me, and which project is heaviest?"
2. **Skill runs prerequisite checks.** Verifies `sqlite3` is on PATH and the database file exists. Fails closed with a message about installing a trusted tracker if missing.
3. **Quick summary first.** One line with today's spend, total, call count, session count.
4. **Cost by project.** Ranked descending. Currency formatted to 4 decimals for small amounts, 2 for larger.
5. **Last-7-days trend.** Date column + cost + call count, ordered by date desc.
6. **Optional session drilldown.** Top 10 most recent sessions with start, end, cost, calls — for the "what did this specific session cost" follow-up.
7. **Format with the reporting checklist.** Today vs. yesterday, total, top projects, top tools, sessions + average.

The discipline that makes it work: the skill never hand-calculates from `input_tokens × pricing`. Every reported number comes from the precomputed `cost_usd` column. Model prices and cache pricing change too often for any hardcoded price table to stay correct — the tracker that wrote the row is authoritative.

## Receipts

_TODO — to be filled in from a real session. Once the skill has been run against a real cost-tracker database, this section will capture: which SQL recipe was the most informative for the operator's actual question (quick summary vs. project breakdown vs. session drilldown), whether the table schema matched the canonical column names or required adapter SQL, how the prerequisite check behaved when `sqlite3` was missing vs. when the database file was absent, and any rounding artifact that surfaced for small (<$0.001) per-call rows._

## Source and attribution

From [Affaan M's everything-claude-code](https://github.com/affaan-m/everything-claude-code/tree/main/skills/cost-tracking) — an MIT-licensed skill collection covering harness construction, agent ops, video, payments, and platform-specific patterns.

License: MIT.

Quoting the anti-fabrication rule verbatim: *"Do not estimate costs from raw token counts when cost_usd is present."* The tracker is the source of truth because pricing changes faster than any skill can keep current — once the tracker has priced a row, recomputing is wrong by definition.