Local-first usage, cost & live-monitor dashboard for your AI coding tools —
Claude Code and Codex CLI, in one place. KPIs, real-time monitor, cost
forecast, session deep-dive, MCP-server breakdown, and a token-saving advisor.
Everything runs on 127.0.0.1. Your data never leaves your machine.
npx github:ShaonPro/TokraxThat's it. The dashboard opens in your default browser at http://127.0.0.1:47776
(port 47776 — ends in 776 = "PRO" on a phone keypad ✦).
No clone, no install, no npm install. Press Ctrl + C to stop.
Heads-up —
npxwill ask once to install. Say yes. Subsequent runs are instant.
npm i -g github:ShaonPro/Tokrax
tokrax # open the web dashboard
tokrax-cli # full report right in your terminalRe-run the npm i -g command to update — npm refetches by commit hash automatically.
If you don't use npm, clone or download the repo and double-click the launcher for your OS:
| OS | Launcher |
|---|---|
| macOS | tokrax.command (right-click → Open the first time) |
| Windows | tokrax.bat |
| Linux | ./tokrax.sh |
- Node.js 22.13+, 23.4+, or 24+ recommended. Older 22 / 23 also work —
the dashboard auto-adds
--experimental-sqlitefor you. Uses Node's built-innode:sqlite, sonpm installis never needed. - At least one supported tool used once (see below).
Windows note — the
npx github:form works in PowerShell, Command Prompt, and Git Bash. If you prefer the launcher, double-clicktokrax.batafter cloning the repo.
The dashboard auto-detects which tools you have and shows a Claude · Codex · All switcher in the header (it only appears when more than one is present).
| Tool | Reads | Data source |
|---|---|---|
| Claude Code | ~/.claude/usage.db + ~/.claude/projects/**/*.jsonl |
SQLite + live JSONL |
| Codex CLI | ~/.codex/sessions/**/rollout-*.jsonl |
live JSONL (parsed in-memory) |
Both are read read-only. Cost is computed locally from token counts using
published API list prices — no network, no auth. On Windows the same paths live
under %USERPROFILE%\.claude\ and %USERPROFILE%\.codex\.
More adapters (Cline, Continue, Aider, Gemini CLI, Cursor) are on the roadmap — one at a time, only when each is rock-solid.
Real-time view of every active Claude Code session, parsed straight from the
JSONL transcripts (~/.claude/projects/). Multi-session aware — if you're
running two windows at once, you see them side-by-side, with last-5-minute
turn / token / cost rollups and the most recent tool calls.
Every project gets a session health audit. Color-coded states
(fresh · healthy · getting-full · near-max · stale · abandoned)
plus a concrete next move: which session to continue, which to /compact,
which to retire for a fresh start.
Knows how many days are left in the month and your recent burn rate. Tells you the projected end-of-month total before you blow the budget.
Switchable across Tokens · Cost · Turns · Output · Cache, area or bar. Hover anywhere on the curve for an exact per-day breakdown.
Every session you've ever run, sorted by recency by default. Filter by project chip, full-text search across project/model/branch, sort any column, click any row to open a deep-dive modal with per-turn context-size timeline and tool breakdown.
Context-aware tips: how full the current window is, whether the cache hit
rate is healthy, when to /compact vs /clear, and durable habits
(point at exact files, keep CLAUDE.md lean, split unrelated tasks).
See exactly which MCP servers your turns hit, with per-tool drill-down.
tokrax-cli # everything, all time
tokrax-cli --range 7d # last 7 days (7d | 14d | 30d | 90d | all)
tokrax-cli --project acme-corp/api # filter to one project
tokrax-cli --json # raw JSON, pipe-friendly(Or node cli.js --range 7d if you didn't install globally.)
The CLI renders the same KPIs, model/project rankings, top tools, daily sparkline, and insights with proper ANSI color — perfect for CI logs or when you don't have a browser handy.
| Env var | Effect |
|---|---|
PORT |
Pick a different port. Auto-tries the next 10 if 47776 is busy. |
NO_OPEN |
Set to anything truthy to skip auto-opening the browser. |
HOST |
Override the bind address. Default 127.0.0.1 — leave it loopback. |
CLAUDE_USAGE_DB |
Point at a different Claude usage.db. |
CLAUDE_USAGE_PROJECTS_DIR |
Point at a different Claude transcripts dir. |
CLAUDE_USAGE_CODEX_DIR |
Point at a different Codex sessions dir. |
Examples:
PORT=8090 npx github:ShaonPro/Tokrax # custom port
NO_OPEN=1 npx github:ShaonPro/Tokrax # don't auto-open browser- Binds to
127.0.0.1only — the dashboard is not reachable from your network. - Database is opened read-only. We never write to
~/.claude/usage.db. - Zero external runtime dependencies — no
npm install, no CDN fetches at runtime. - No telemetry, no analytics, no tracking pixels. Nothing phones home.
- Cost numbers are estimated Anthropic API list prices, not your Claude Code subscription bill — shown so you can see the dollar value of the work you ran locally.
server.js Local HTTP server + JSON API (binds to 127.0.0.1)
stats.js Reads ~/.claude/usage.db + JSONL files, applies pricing,
aggregates, classifies session health
dashboard.html Single-page web UI — vanilla JS, custom SVG charts,
no CDN, no build step
cli.js ANSI-colored terminal dashboard
tokrax.* One-click launcher per OS
The dashboard polls two endpoints:
GET /api/statsevery 30 s — the heavy aggregates (KPIs, charts, sessions) derived from~/.claude/usage.db.GET /api/liveevery 5 s — the Live Monitor reads the most-recently- modified.jsonlfile in~/.claude/projects/directly, so it's fresh within seconds (the SQLite cache rebuilds on a much slower schedule).
Per-session deep-dive uses GET /api/session/:id and parses just that
session's turns.
Hover any card (or the KPI grid) → click the camera icon → pick PNG or SVG and one of six gradient backgrounds → get a Mac-window-framed image with a low-key watermark.
- PNG (default) — a real raster image that opens anywhere:
Photoshop, Preview, Slack, X, LinkedIn. Rendered locally via a vendored
html2canvas(no CDN). Also copied to your clipboard for instant paste. - SVG — vector, tiny, lossless — best opened in a browser or Figma.
(Note: SVG embeds the live DOM via
foreignObject, which only renders in web browsers — use PNG if you need Photoshop/Preview.)
The screenshots above use fake projects, costs, and models — no real data is ever shown.
| File | Purpose |
|---|---|
server.js |
Local HTTP server + JSON API |
stats.js |
Data layer — transcripts/SQLite, pricing, aggregation |
dashboard.html |
Single-page web UI |
cli.js |
Terminal dashboard |
tokrax.command/.bat/.sh |
One-click launchers per OS |
html2canvas.min.js |
Vendored — powers portable PNG capture |
test/stats.test.js |
Zero-dependency test suite (node --test) |
.github/workflows/ci.yml |
CI matrix — Node 22+24 × Ubuntu+Windows+macOS |
Contributions are very welcome — the project is small, dependency-free, and local-first by design. Bug fixes, adapters, and UX polish are all great places to start.
- 📋 CONTRIBUTING.md — dev setup, ground rules, PR checklist
- 🗺️ ROADMAP.md — what's planned next, what's explicitly out of scope
- 🐛 Open a bug · ✨ Request a feature
- 📜 CHANGELOG.md — what's changed across versions
- 💬 Code of Conduct — be kind, be specific
Looking for an easy first PR? Check the
good first issue
label. Adding a new tool adapter is a particularly contained change — see the
Roadmap.
git clone https://github.com/ShaonPro/Tokrax && cd Tokrax
node server.js # runs against your real data on http://127.0.0.1:47776
npm test # self-contained tests (build their own fixtures, zero deps)The dashboard is built around one promise: your usage data never leaves your machine. That promise is enforced in code — read SECURITY.md for the line-by-line guarantees, the threat model, and how to responsibly report a vulnerability (email [email protected], not a public issue).
MIT — see LICENSE.
✦ Customized by ShaonPro ✦