Get started fast.

TokenTrace runs on Node.js with zero install scripts, no preinstall hooks, and no API key. The published npm package runs no TokenTrace code at install time. Run through npx for a single session, or install globally to keep the CLI on your PATH.

Requires Node.js 20.9.0 or newer. Works on macOS, Linux, and Windows.

TokenTrace ships a small vocabulary the rest of the page reuses. None of it is jargon for its own sake.

• Parser. A typed reader for one AI CLI's local artifacts (Claude Code, Codex, OpenAI). Parsers know where each CLI writes its records and how to normalize them into a common shape.
• Scan. Reads the local artifacts, normalizes token usage, attaches a confidence label to every record, and writes the result to a local SQLite database. Re-runs are idempotent.
• Data Confidence. A label attached to every record: exact (read directly from the CLI's own counts), tokenizer estimate (counted with a local tokenizer), or simple estimate (heuristic when neither is available). Aggregates split back into measured versus estimated portions.
• Model Rate. Pricing per model, refreshed by the one optional outbound call. Drives the cost column.
• Evidence pack. Every total in the dashboard traces back to the sessions and source files that produced it. tokentrace evidence --json prints the same trail as JSON.
• Repair. The workflow for fixing unknown-cost rows: assign model aliases, run auto-classify, backfill cost for matching interactions.
• Anomaly. A daily token or cost bucket flagged by a MAD-based z-score detector as notable, high, or severe. Surfaces in the dashboard and via MCP.

The default command starts a local dashboard, picks an available localhost port starting at 3030, opens your default browser, and keeps the server running until you press Ctrl+C. The Overview surfaces Usage Pulse, token accounting, Model Rates, and Trend charts; every card links into the evidence trail behind its total.

Pass --port or --no-open to pin a port or skip the browser launch.

Drop a live token, cache, cost, and Model Rate readout at the bottom of every Claude Code session. The setup command writes the status-line config for Claude Code; restart your session and the line appears.

The status line separates context-in-flight (what Claude is carrying now) from cumulative processed and cache usage (what the session has used so far), so you stop misreading tokens-used as tokens-in-context. The Model Rate state at the right tells you whether the cost column is exact or estimate.

tokentrace mcp exposes the same usage data to AI agents over a local stdio MCP server. Agents call get_agent_guide first to discover the tool surface, then read what they need.

The tool surface is read-only by default. run_scan is the one exception and it requires explicit human confirmation each time. A bounded local agent-action log keeps every tool call auditable, and a handoff envelope passes scoped context between an orchestrator and a sub-agent without leaking the rest of the database.

Useful tools out of the box: get_usage_overview, query_usage, get_anomalies, get_classifications, get_evidence.

When the dashboard is not the right surface (a CI job, a script, or an agent), the CLI prints the same data as JSON.

tokentrace query runs parameterized SQL aggregations: group by model, project, tool, session, or day; aggregate cost, total_tokens, or interaction_count; filter and window by a preset (7d, 30d, mtd) or explicit date range. No natural-language parsing is involved; the CLI takes structured arguments and runs deterministic SQL.

tokentrace evidence --json prints the metric evidence trail behind any total. tokentrace anomalies lists recent anomaly buckets with severity and the date range. tokentrace agent --json returns the agent discovery manifest if you are wiring TokenTrace into a custom orchestrator.

Unknown-cost rows appear when TokenTrace cannot match a model name to a Model Rate. The repair workflow turns those rows into priced records without you editing the database by hand.

tokentrace repair lists unknown-cost groups by cause, with alias hints and Parser review links.

tokentrace repair auto-classify emits suggestions for each group using three confidence-ordered rules: exact-model (0.95), family-fragment (0.70), and parser-source (0.45). Run it with --dry-run first to preview, then apply.

tokentrace repair auto-classify --apply (confidence floor 0.85) persists qualifying suggestions to the model_aliases table and backfills cost for matching interactions. The apply path runs inside a single SQLite transaction, so a failure partway cannot leave the database half-applied.

TokenTrace reads files the AI CLIs already write to your disk. Nothing else.

• No scraping, no extensions, no proxy, no MITM. No browser instrumentation, no traffic interception. The dashboard is a localhost server you start on demand.
• Raw prompt and response bodies are skipped by default. TokenTrace stores token counts, model names, timestamps, and cost; it does not store what you sent or what the model said.
• One optional outbound call. Refreshes public Model Rate data so the local cost estimate stays accurate. Opt out and cost columns show as estimate instead of exact.
• No accounts, no telemetry, no analytics ping. No usage reporting back to anyone.
• Zero install scripts. npm install tokentrace runs no TokenTrace code. No preinstall, install, or postinstall hooks.
• npm provenance + readable source. Every release ships an npm provenance attestation, so anyone can verify the published package matches the public source. The package ships readable application source, not opaque bundles.

The trust contract appears in the running app at Settings, Package trust. It is the same one written here.

Most first-run issues land in a handful of buckets.

• Dashboard shows zero usage. The scan picked nothing up. Run tokentrace scan manually and check the output for parser warnings. tokentrace doctor --json prints the Parser Trust Report (files checked, ignored support files, parser warnings, cost coverage, supply-chain IOC checks); pipe it through jq to find the specific concern.
• Many unknown-cost rows. The new model is missing from Model Rates or the parser emits an alias TokenTrace has not learned yet. Run tokentrace repair auto-classify --dry-run to preview suggestions, then apply.
• Anomalies look wrong on a flat window. The MAD detector returns a finite sentinel z-score when mad === 0 (a flat-window edge case) instead of silently dropping the signal as Infinity would.
• Status line not appearing in Claude Code. Re-run tokentrace statusline setup claude and restart your Claude Code session. The setup writes a config snippet Claude reads on startup.
• Model Rate refresh blocked by the network. The one outbound call is optional; if it is blocked, the cost column degrades to estimate rather than failing. Settings let you turn the refresh off explicitly.
• Scheduled scan ran twice. Concurrent scans are coalesced behind an in-flight promise guard from 0.18.1 onward. If you are still on an older release, upgrade.

For anything else, start with tokentrace doctor --json. It names the failing subsystem and the next command.