Beautiful dashboard showing a breakdown of where all of your tokens are going
npx token-usage-dashboard
Ever wondered where all your tokens are going? Or how much your AI usage is valued at? This usage dashboard reads your local Claude Code, Codex, Open Code transcripts and builds a beautiful dashboard breaking down your full historical usage.
Everything happens locally, so your data never leaves your device. Stats are cached in a local SQLite DB, so that you get full history even after Claude and Codex have pruned old transcripts. Cost estimates come from current published API rates.
The dashboard shows:
- a calendar heatmap of every day since your records start
- daily totals, stacked by tool, model and project
- the split between fresh input, output, cache reads and cache writes
- which projects, AI providers and models the your tokens went to
- Anthropic and OpenAI 5-hour and 7-day windows
- every session, with full token usage breakdown
npx token-usage-dashboardThat's it. It finds your transcripts, reads them, and opens on
localhost:4747. Install it globally and the command is just aiusage.
Nothing leaves the machine except the one call to Anthropic for your plan windows, which you can
turn off in settings.
| Flag | What it does |
|---|---|
-p, --port <n> |
Port to listen on, or the next free one after it |
-h, --host <ip> |
Address to bind, 127.0.0.1 by default |
--db <path> |
Where to keep the history |
--open / --no-open |
Whether to open a browser |
Most of it lives behind the gear icon: theme, default range, how often to rescan, whether to ask Anthropic for your plan windows, and price overrides for any model we've got wrong or don't know.
Paths are environment variables, since they're needed before the app starts. See
.env.example for the full list. The ones you'll actually want are
AIUSAGE_DB, AIUSAGE_CLAUDE_DIR and AIUSAGE_CODEX_DIR.
| Tool | Where it reads |
|---|---|
| Claude Code | ~/.claude/projects/**/*.jsonl, subagent transcripts included |
| Codex | ~/.codex/sessions/**/*.jsonl |
| OpenCode | ~/.local/share/opencode/storage/message |
Adding another is one file in src/lib/server/sources/. If a tool writes token counts somewhere
we can read, it can go in - open an issue with a sample and we'll have a look.
The image is on DockerHub (notaflightrisk/ai-usage-dashboard)
and GHCR. Mount the directories you want read, plus somewhere to keep the database:
docker run -p 127.0.0.1:8080:8080 \
-v ~/.claude:/home/node/.claude:ro \
-v ~/.codex:/home/node/.codex:ro \
-v ai-usage:/data \
notaflightrisk/ai-usage-dashboardThere's a compose file in docker/ if you'd rather. The container has
to bind 0.0.0.0 internally, so publish the port to localhost like that unless something in
front of it is checking who's asking.
There's a systemd user unit in scripts/. scripts/install.sh fills in the paths and starts it,
so it comes back after a reboot:
./scripts/install.sh 4747Grab the tarball from releases,
then npm ci --omit=dev && npm start.
Follow Development below, then npm run build && npm start.
You'll need Node 22.12 or newer, plus Git. It's a SvelteKit app and the build is self-contained so there's no runtime dependencies at all.
git clone git@github.com:NotAFlightRisk/ai-usage-dashboard.git
cd ai-usage-dashboard
npm install
npm run devThe dev server is then on localhost:5173.
The other scripts you'll want are npm run check (types), npm test (tests) and npm run format (prettier).
Licensed under MIT, © NotAFlightRisk 2026
