Claude Code Token Usage

Claude Code Token Usage

What your Claude Code sessions cost, project by project, then what filled the context inside each one.


Reads `~/.claude/projects/**/*.jsonl` locally. No transcript, no prompt, no filename ever leaves your machine. Python 3.10+, stdlib only.

Install as a skill

The repository *is* a Claude Code skill. Clone it into `~/.claude/skills/`:

git clone https://github.com/pierrebelin/claude-code-token-usage.git ~/.claude/skills/token-usage

Copy **everything** — `SKILL.md`, `cc-usage.py`, `cc-usage-template.html`, `README.md`. The script looks for the template in its own directory, and the folder name is what `/token-usage` resolves to.

Then ask in plain language:

> how much have I spent this month?
> which project costs me the most?
> what filled the context of session 46e2620d?
> open the usage dashboard

`SKILL.md` also tells Claude how to *read* the result: which sessions are exact and which are a floor, why a re-read after a compaction is not waste, what the carry factor means. That reading grid is why the skill install beats a bare script.

Dashboard

python3 ~/.claude/skills/token-usage/cc-usage.py --serve

`http://127.0.0.1:8787/`, loopback only, re-runs the analysis on every load (~0.8 s). Home page: counters, cost per project, daily curve, session list. Each row opens its own page (~0.1 s), showing the per-tool breakdown and every turn.


Sort and filter are GET forms: state lives in the URL, so `?days=30&sort=date-desc&q=backend` is shareable, and nothing depends on JavaScript.

A frozen, self-contained HTML file instead of a server:

cc-usage.py --days 30 --dashboard report.html
cc-usage.py --dashboard session.html --focus 420f8978   # one session

Terminal

The script is standalone:

echo "alias c