localhost:3030 / Overview

Overview

Built: 2026
Version: 0.18.1
Category: Developer Tools / local analytics
Runtime: Node.js 20.9.0+
OS: macOS, Linux, Windows
Surfaces: 11
Price: Free (MIT)

When an AI CLI does real work, it writes usage records to disk as it goes. TokenTrace reads those local artifacts from Claude Code, Codex, OpenAI, and other tools, normalizes the token usage, estimates missing counts when it has to, and shows cost, models, projects, sessions, and parser evidence in a local dashboard.

Everything lives in one local SQLite database. Every total traces back to the sessions and source files that produced it, every record carries a Data Confidence score, and you can export any total as an Evidence Pack. No cloud account, no telemetry, no proxying.

TokenTrace is one of two related developer-tools projects here. ProjScan gives AI coding agents real structural facts about your codebase; TokenTrace shows you, after the fact, what those agents and their CLIs cost. Ingestion reads only the local filesystem on purpose: desktop scraping, browser extensions, traffic interception, and cloud telemetry change the trust profile, so they stay off the roadmap.

Features

What it does well.

01

Evidence-first overview

Usage Pulse, token accounting, Model Rates, and Trend charts. Every total points back to the records that produced it.

02New in 0.18.0

Local intelligence

Anomaly detection flags unusual days in the trend, structured query answers agent questions with deterministic SQL, and the unknown-cost auto-classifier suggests model aliases for unpriced rows. All three run on local SQLite with no AI tokens.

03Upgraded in 0.16.0

MCP entry point

tokentrace mcp starts a local stdio MCP server. Agents call get_agent_guide first, then pick from a read-only tool surface; run_scan needs explicit human confirmation. 0.16.0 adds a handoff envelope and a bounded local agent-action log.

04New in 0.12.0

Local sources and trust

Reads JSON, JSONL, SQLite, and Cursor exports the AI CLIs already write on disk. Every record carries a Data Confidence score.

05Upgraded in 0.16.0

Scan Health

Files checked, Parser warnings, ignored support files, cost coverage, scan scheduling, supply-chain IOC checks, and parser overrides for selective ingestion, all in one view.

06

Repair workflow

Unknown-cost rows grouped by cause, with the next best repair next to the evidence. A before/after delta runs before you commit.

07New in 0.12.0

Evidence Packs

Export the trail behind any total as JSON or Markdown. No raw prompts by default, so usage evidence is safe to share.

08New in 0.16.0

Saved reports

Reusable report templates stored locally. Replay any saved report on demand, or export it as JSON, Markdown, or a standalone XSS-safe HTML file you can archive.

09

Agent-ready entry points

A read-only discovery manifest over CLI and HTTP, plus agent-adoption docs and an llms.txt index, so any agent can find the surface.

10Upgraded in 0.17.0

Performance and mobile

Streaming render path, tuned SQLite, a prepared-statement cache, and hash-cached rescans, plus mobile card layouts for Repair and Model Rates so the dashboard reads one-handed.

11

Privacy

No telemetry, no proxy, no cloud account. Local files never leave the machine. The only network call refreshes public Model Rates.

See it in action

A closer look.

TokenTrace Evidence detail page tracing a processed-tokens total back to sessions, source files, Parsers, and Model Rates — Evidence trail behind any total
Trace a processed-tokens total back to its sessions, source files, Parsers, and Model Rates. tokentrace evidence --json prints the same trail.

TokenTrace Unknown Cost Repair workflow grouping unknown-cost rows by cause, with alias hints, parser review links, and Model Rate follow-up — Unknown-cost rows, grouped by cause
Each group carries alias hints, Parser review links, and a Model Rate follow-up, with a before/after delta before you commit.

TokenTrace Scan Health: files checked, Parser warnings, ignored support files, cost coverage, scan scheduling, and supply-chain IOC checks — Scan Health and the Parser Trust Report
Files checked, Parser warnings, cost coverage, scan scheduling, and supply-chain IOC checks, all in one view.

TokenTrace Settings package trust panel summarizing install-script, network, and provenance guarantees — The trust contract, shown in-app
The same install-script, network, and provenance guarantees, visible inside the running app at Settings, Package trust.

A Claude Code session with a TokenTrace status line showing session tokens, cache, cost, and Model Rate state — A live status line for Claude Code
Session tokens, cache, cost, and Model Rate state at the bottom of the session. It separates live context, what Claude is carrying now, from cumulative processed and cache usage, so you stop misreading tokens used as tokens in context.

Release notes

Shipped in 0.18.x.

The local intelligence bundle: three deterministic features that sharpen the dashboard and MCP surface without spending a token from your AI budget.

Anomaly detection: A modified z-score (MAD) detector runs over the daily token and cost trend and flags unusual days as notable, high, or severe. A new Anomalies panel lists recent anomalies with clickable date links that filter the whole dashboard to that day, and the Trend charts render colored markers on flagged buckets. Available as tokentrace anomalies and MCP get_anomalies.
Structured query: tokentrace query, MCP query_usage, and a new query page run parameterized SQL aggregations: group by model, project, tool, session, or day; aggregate cost, total tokens, or interaction count; filter and window by a preset or explicit date range. The agent supplies structured arguments and TokenTrace runs deterministic SQL, with no natural-language parsing involved.
Unknown-cost auto-classifier: tokentrace repair auto-classify and MCP get_classifications emit suggestions for each unknown-cost group using three confidence-ordered rules: exact-model (0.95), family-fragment (0.70), and parser-source (0.45). The apply path (floor 0.85, with a dry-run preview) persists qualifying suggestions to a model_aliases table and backfills cost for matching interactions.

Stable surface

What npm install ships.

The trust contract behind the version pill: privacy, package guarantees, runtime, and what the one network call does.

Local files stay local: TokenTrace reads files the AI CLIs already write on your disk. No scraping, no extensions, no traffic interception, no proxy, no MITM, and raw prompt and response bodies are skipped by default.
No telemetry, no accounts: No usage telemetry, no analytics ping, no accounts. The one optional outbound call refreshes public Model Rate data so the local cost estimate stays accurate. TokenTrace never bills you.
No install scripts: npm install tokentrace runs zero TokenTrace code. The package has no preinstall, install, or postinstall hooks.
npm provenance: Every release ships an npm provenance attestation, so anyone can verify on npm that the published package matches the public source repo.
Readable source: The published package ships readable application source and the compiled CLI runtime, not generated route bundles. Anyone can read what runs.
Runtime: Node.js 20.9.0+ for the dashboard and CLI, on macOS, Linux, and Windows. Each record carries a Data Confidence label (exact, tokenizer estimate, or simple estimate), so aggregates split back into measured versus estimated portions.