# token-dashboard: reading Claude Code's transcripts to see where the tokens went

> token-dashboard is a local Python tool that parses the JSONL transcripts Claude Code writes to your home directory and turns them into per-prompt cost analytics, tool heatmaps and cache statistics, served by a small local web app. It never modifies the transcripts, it caches into SQLite, and it deduplicates the streaming snapshots that make raw counts look wrong.

**nateherkai/token-dashboard** — See where Claude Code is burning tokens - turn raw JSONL transcripts into local cost analytics, hotspot views, and session-level usage insight.

- Repository: https://github.com/nateherkai/token-dashboard
- Stars: 739 · Forks: 204
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nateherkai-token-dashboard

## Local analysis of transcripts Claude Code already writes

token-dashboard is a local dashboard that reads the JSONL transcripts Claude Code writes to the projects directory in your home folder, and turns them into per-prompt cost analytics, tool and file heatmaps, subagent attribution, cache analytics, project comparisons and a rule-based tips engine.

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

That framing is the whole design. There is no scraping of the Claude API, no account to create, no token to paste, and no scheduled call to a vendor endpoint. The dashboard is a reader for a file format that another tool already produces, which means it can be added to a machine that already runs Claude Code and will start producing numbers after the first session.

The use cases in the README are specific and worth reading because they tell you what the tool is trying to answer. You can see which of your prompts are expensive, and the parenthetical is that they usually involve large tool results. You can compare token usage across projects. You can spot wasteful patterns, such as the same file read twenty times in a session or a tool call returning 80k tokens. You can understand what a cache hit actually saves you. And if you are on the Pro or Max plan, you can confirm you are getting your money's worth in API-equivalent dollars.

The licence is MIT, the primary language is Python, the default branch is main, and the last push was on 2026-04-20. There are no GitHub releases, so the source is the product.

## Running it, and what the command actually does

There is no pip install, no Node.js and no build step. The prerequisites are Python 3.8 or newer, which is already installed on macOS and most Linux, Claude Code installed with at least one session run, and a web browser.

The Claude Code requirement has a condition that trips people up. The dashboard reads existing sessions, so if you have just installed Claude Code and have not used it yet, there is nothing to read, and you need to run at least one prompt first.

The quickstart is three commands:

```bash
git clone https://github.com/nateherkai/token-dashboard.git
cd token-dashboard
python3 cli.py dashboard
```

On Windows, if python3 is not on your path, substitute py -3 for python3 in every command.

The dashboard command does three things. It scans the projects directory, which on a first run can take 20 to 60 seconds on a heavy user's machine. It starts a local server on the loopback address at port 8080. And it opens your default browser to that address.

Then you leave it running. It re-scans every 30 seconds and pushes updates live, and you stop it with Ctrl+C.

You can point it at a different location with two flags:

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

which is what you would use if your Claude Code data lives somewhere other than the default, or if you want the cache on a different volume.

## The environment variables, and the one that can leak your prompts

There are four environment variables, and the table is short enough to read in one go.

PORT defaults to 8080 and is the port the local web server listens on. HOST defaults to 127.0.0.1 and is the bind address, and the README's advice here is unusually emphatic. Keep the default. Setting it to 0.0.0.0 exposes your entire prompt history to anyone on your local network, and the note says do not do this on any network you do not fully control, with coffee-shop wifi and coworking spaces given as examples.

That is the one real risk in the project, and it is worth understanding why it exists. The server has no authentication, and the data it serves is the complete history of what you have asked an AI, including whatever was in the file contents you read. The default binding to loopback is the only thing standing between that and the local network, so the setting is not a stylistic preference.

CLAUDE_PROJECTS_DIR defaults to the projects directory under your home folder and is where to scan for session JSONL files. TOKEN_DASHBOARD_DB defaults to the token-dashboard database in the same place and is the SQLite cache location.

Pricing is a file rather than a constant, in pricing.json, and the README says to edit it directly if model prices change or to add a new plan. That is a sensible choice given how often model pricing moves, and it means the cost figures are as accurate as the file you keep.

## Seven tabs, and the data each one shows

The dashboard is a single page with a hash-router tab bar across the top, and each tab is backed by its own JSON API under the api path.

Overview is the landing tab: all-time input, output and cache tokens, sessions, turns, estimated cost on your chosen plan, daily work and cache-read charts, tokens by project, token share by model, top tools by call count, and recent sessions. It also has a built-in panel called What do these numbers mean that explains the input, output and cache token categories in plain English.

Prompts ranks your most expensive user prompts by tokens, and clicking a row shows the assistant response, the tool calls made and the size of each tool result. That is the tab that answers the question the project exists for.

Sessions is a turn-by-turn view of a single session with per-turn tokens and tool calls. Projects compares projects by tokens, session counts and which files were touched most.

Skills shows which skills you invoke most often and, where they can be measured, their token cost, with a pointer to a known limitations document that says the skill token counts are partial.

Tips gives rule-based suggestions for reducing token usage, covering repeated file reads, oversized tool results and a low cache-hit rate. And Settings switches the pricing between API, Pro, Max and Max-20x so the cost figures everywhere else reflect your actual plan.

The rules engine being rule-based rather than learned is worth noting, because it means the advice is reproducible and explainable rather than a guess.

## The deduplication problem, and why other numbers look higher

This is the part of the README that decides whether you trust the output, and it is the most useful thing in the document for anyone comparing figures.

Claude Code writes each assistant response two to three times to disk while it streams, because the same API message gets written out repeatedly as the output grows. The dashboard deduplicates these by the message id, so the final tally matches what the API actually billed. And the README says if you compare against another tool that sums every JSONL row, expect this dashboard's numbers to be lower, and closer to reality.

That is a strong claim, and it is the kind of claim that a tool has to earn. A naive analyser over these files will over-count by a factor of two or three, which is exactly the kind of error that makes people abandon a cost tracker. Deduplicating on the message id and saying plainly that other tools will show more is the behaviour you want from a measurement tool.

The data flow is simple enough to reason about. The command line entry point calls the scanner, which writes to the SQLite database, and the server module exposes the JSON API routes and serves the web directory. The cache is what makes the 30 second re-scan cheap, and it is also why the troubleshooting section tells you to delete the database file and re-run the scan command if the numbers look wrong or stuck.

Two more operational notes from the troubleshooting section. If you get no data or empty charts, run the scan command once to populate the database and reload. And do not run the dashboard twice at the same time, because both processes will fight over the SQLite database, so stop all instances before starting a new one.

## Where token-dashboard is the wrong choice

The first wrong case is a team sharing a machine. The data source is a directory of transcripts in one user's home folder, and the tool is built for one person on one machine. There is no multi-user model, and if you run the dashboard as a shared service on a build box, the HOST warning applies with full force.

The second is a workflow where the sessions are not on your disk. If you use Claude Code through a remote or containerised setup where the transcripts live elsewhere, the tool has nothing to read, and the --projects-dir flag helps only if the files are reachable from where you run it.

The third is anyone who needs the numbers to be authoritative for a budget. The cost figures are derived from a pricing.json you maintain, and the skill token counts are explicitly partial. This is a personal diagnostic tool, and it says so, and using it as the source of truth for a team budget means owning the pricing file and the caveats.

The fourth is a project that has already solved this. Some environments already have usage reporting, and a platform team may have a cost attribution pipeline that answers the same questions with the org's own numbers, which will be more accurate than reconstructing from transcripts.

The alternative worth weighing is reading the JSONL yourself. The format is a plain file per session, and a dozen lines of Python will give you a token count for a session. What you give up is the deduplication, the tool attribution, the cache-hit accounting and the per-prompt ranking, which is to say, most of the work this tool has already done.

## Conclusion

Adopt token-dashboard if you are paying for Claude Code by subscription and want to know which of your prompts and tools actually cost you, since it works from the transcripts Claude Code already writes and needs no account, no install and no network. Keep away if your sessions are not on the machine where you run it, because the data source is a local directory, and be careful about the bind address, since the README warns that setting HOST to 0.0.0.0 exposes your entire prompt history to the local network. Before you trust the numbers, read the accuracy note about deduplication, and note the last push was on 2026-04-20 with no tagged releases.

## FAQ

### What is token-dashboard and what does it read?

It is a local dashboard that reads the JSONL transcripts Claude Code writes to the projects directory under your home folder, per session, and turns them into per-prompt cost analytics, tool and file heatmaps, cache analytics, project comparisons and rule-based tips. It never modifies those files, and it keeps a local SQLite cache.

### How do I run token-dashboard?

Clone the repository, change into the directory and run python3 cli.py dashboard. There is no pip install, no Node.js and no build step. The command scans the projects directory, which can take 20 to 60 seconds on a heavy first run, starts a local server on port 8080, and opens your browser, then re-scans every 30 seconds with live updates.

### Why do the token numbers differ from other tools that read the same files?

Claude Code writes each assistant response two to three times to disk while it streams, snapshotting the same message as the output grows. The dashboard deduplicates by message id, so its totals match what the API billed, and the README says a tool that sums every JSONL row will show higher numbers.

### Is it safe to run token-dashboard on an untrusted network?

Keep the HOST setting at its default of 127.0.0.1. The README warns that binding to 0.0.0.0 exposes your entire prompt history to anyone on the local network, and advises not doing it on any network you do not fully control, with coffee-shop wifi and coworking spaces named as examples.

## Sources

- [Issues](https://github.com/nateherkai/token-dashboard/issues)
- [License: MIT](https://github.com/nateherkai/token-dashboard/blob/main/LICENSE)
- [nateherkai/token-dashboard on GitHub](https://github.com/nateherkai/token-dashboard)
- [README](https://github.com/nateherkai/token-dashboard/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nateherkai-token-dashboard