Tracking token usage accurately when interacting with AI models like Claude often feels like guesswork. Claude Code writes each assistant response multiple times during streaming, which inflates naive token counters that sum every JSONL line. token-dashboard tackles this problem head-on by parsing Claude Code’s session transcripts and deduplicating tokens by message ID, resulting in token tallies that reflect actual API billing. It does all this without any external dependencies, no pip installs, and no build steps — just Python 3 standard library and a local SQLite cache.
what token-dashboard does and how it works
token-dashboard is a command-line tool written in Python 3 that scans Claude Code’s JSONL session transcripts stored in ~/.claude/projects/. These transcripts record all user and assistant messages along with token usage metadata. However, Claude Code streams assistant responses in multiple partial snapshots, writing them repeatedly to disk during generation. This causes naive analyzers to double- or triple-count tokens.
This repo’s key feature is its deduplication logic, which uses the unique message.id field to identify and consolidate repeated snapshots of the same message. This produces accurate token counts that better match the actual API billing, rather than inflated sums.
Under the hood, token-dashboard stores parsed and deduplicated data in a local SQLite database, providing a caching layer that speeds up repeated scans. The tool includes a built-in HTTP server implemented with Python’s standard http.server module. It exposes JSON APIs for frontend consumption and supports server-sent events for live updates.
The frontend is a simple single-page app written in vanilla JavaScript and ECharts for visualizing token usage over time. It uses hash-based routing and listens to server-sent events to refresh the dashboard live every 30 seconds when new data is scanned.
The entire stack is zero-dependency: no external Python packages, no Node.js, and no build process. This makes it easy to run on any system with Python 3.8+ installed, including macOS and Linux systems where Python is pre-installed.
the deduplication mechanism and design tradeoffs
The most technically interesting aspect is the deduplication of streaming snapshots by message.id. Claude Code writes each assistant message multiple times during generation, so each JSONL transcript can have repeated partial messages with different token counts.
Instead of summing token usage across all lines, token-dashboard keeps only the latest version for each unique message.id. This logic is crucial for producing token tallies that are consistent with actual consumption and billing.
This approach trades off some complexity in parsing for accuracy. The code is surprisingly clean and readable, relying on Python’s built-in JSON parsing and SQLite interfaces. The SQLite cache means subsequent scans are much faster than the initial import, which can take 20–60 seconds on a heavy user’s machine.
The built-in HTTP server and SSE implementation in pure stdlib Python is a neat engineering choice. It avoids any dependency on frameworks like Flask or FastAPI, reducing the setup footprint drastically. The frontend’s reliance on vanilla JS and ECharts keeps the client lean and simple, though it lacks some polish you’d expect from heavier SPA frameworks.
The live refresh every 30 seconds is a practical feature that keeps the dashboard updated without manual reloads. This is useful when you’re actively working with Claude Code.
One limitation is the initial scan time, which might feel slow if you have large transcript histories. Also, since the tool only supports Claude Code’s transcript format, it’s not a generic token analytics tool for other LLMs or APIs.
Quick start
git clone https://github.com/nateherkai/token-dashboard.git
cd token-dashboard
python3 cli.py dashboard
On Windows, if python3 isn’t on your PATH, substitute py -3 for python3 in every command.
This command:
- Scans
~/.claude/projects/for transcripts (first run can take 20–60 seconds on a heavy user machine). - Starts a local HTTP server at
http://127.0.0.1:8080. - Opens your default browser to that URL.
Leave it running to get live updates every 30 seconds. Stop with Ctrl+C.
verdict
token-dashboard is a niche but practical tool for anyone using Claude Code who wants accurate, local token cost analytics without external dependencies or complicated setup. The deduplication by message.id is a simple yet effective solution to a common token counting pitfall when dealing with streamed assistant messages.
Its zero-dependency Python 3 approach makes it very accessible, especially for macOS and Linux users with Python pre-installed. The live dashboard with server-sent events provides a nice developer experience for monitoring token usage in real time.
If you have large transcript histories, expect the initial scan to take some time, but subsequent updates are fast thanks to SQLite caching. The tool’s scope is limited to Claude Code transcripts, so it’s not a replacement for multi-LLM or API-agnostic token analytics.
Overall, it’s a solid utility for Claude Code users who appreciate a local, privacy-conscious, and dependency-free solution to token monitoring.
Related Articles
- Pydoll: Async-native Chromium automation with typed extraction for web scraping — Pydoll is a Python library for Chromium automation using Chrome DevTools Protocol. It offers async-native APIs and Pydan
- Maigret: A resilient OSINT username scraper across thousands of sites — Maigret is a Python-based OSINT tool that scrapes public profiles by username from 3,000+ sites without API keys. It fea
- Colly: high-performance web scraping in Go with concurrency and ease — Colly is a Go web scraping framework offering fast, concurrent crawlers with a clean API. It handles cookies, sessions,
- httpie/cli: A human-friendly command-line HTTP client for API interaction — HTTPie CLI offers a simple, readable way to interact with HTTP APIs via command line, with built-in JSON support and col
- how awesome-claude-skills turns claude into a real-world action agent — Awesome Claude Skills is a modular Python framework that empowers Claude to perform real-world actions by integrating wi
→ GitHub Repo: nateherkai/token-dashboard ⭐ 344 · Python