Token Dashboard

A local dashboard that reads the JSONL transcripts Claude Code writes to ~/.claude/projects/ and turns them into per-prompt cost analytics, tool/file heatmaps, subagent attribution, cache analytics, project comparisons, and a rule-based tips engine.

Everything runs locally. No data leaves your machine — no telemetry, no API calls for your data, no login.

What this is useful for

• Seeing which of your prompts are expensive (surprise: they usually involve large tool results).
• Comparing token usage across projects you've worked on.
• Spotting wasteful patterns — the same file read twenty times in a session, a tool call returning 80k tokens.
• Understanding what a "cache hit" actually saves you.
• If you're on Pro or Max, confirming you're getting your money's worth in API-equivalent dollars.

Prerequisites

• Python 3.8 or newer — already installed on macOS and most Linux. On Windows: winget install Python.Python.3.12 or download from python.org.
• Claude Code — installed and with at least one session run. The dashboard reads those sessions. If you just installed Claude Code and haven't used it yet, run at least one prompt first.
• A web browser. Any modern one.

No pip install. No Node.js. No build step.

Quickstart

git clone 
cd token-dashboard
python3 cli.py dashboard

On Windows, if python3 isn't on your PATH, substitute py -3 for python3 in every command below.

The command:

1. Scans ~/.claude/projects/ (first run can take 20–60 seconds on a heavy user's machine).
2. Starts a local server at
3. Opens your default browser to that URL.

Leave it running; it re-scans every 30 seconds and pushes updates live. Stop with Ctrl+C.

Where the data comes from

Claude Code writes one JSONL file per session here:

| OS | Path | |---|---| | macOS / Linux | ~/.claude/projects//.jsonl | | Windows | C:\Users\\.claude\projects\\.jsonl |

The dashboard never modifies those files — it only reads them and keeps a local SQLite cache at ~/.claude/token-dashboard.db.

To point at a different location:

python3 cli.py dashboard --projects-dir /path/to/projects --db /path/to/cache.db

Environment variables

| Var | Default | Purpose | |---|---|---| | PORT | 8080 | Port the local web server listens on | | HOST | 127.0.0.1 | Bind address. Keep the default. Setting 0.0.0.0 exposes your entire prompt history to anyone on your local network — don't do this on any network you don't fully control (no coffee-shop Wi-Fi, no coworking spaces). | | CLAUDE_PROJECTS_DIR | ~/.claude/projects | Where to scan for session JSONL files | | TOKEN_DASHBOARD_DB | ~/.claude/token-dashboard.db | SQLite cache location |

Pricing lives in pricing.json. Edit it directly if model prices change or to add a new plan.

CLI reference

python3 cli.py scan          # populate / refresh the local DB, then exit
python3 cli.py today         # today's tota