The full TokenTrace surface

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

Usage Pulse

A live pulse at the top of the dashboard summarises what you spent today, this week, and this month, with a delta against the previous period. Any row clicks through into the evidence trail behind it.

Token accounting

Tokens split into processed, non-cache, and cache read/write so cache-heavy sessions do not silently inflate the headline. Processed tokens are cumulative processed usage, not current context size.

Model Rates

Cost estimates per session, model, and project, with a coverage indicator for how many records matched a Model Rate. Rows without a rate group by cause and link straight into the Repair workflow. Model Rates are only used to estimate provider costs locally; nothing is billed.

Trend charts

Token Trend and Cost Trend charts sit right after Usage Pulse, so weekly and monthly shifts surface without leaving the page. The same evidence trails reach back into the Repair workflow when an unexpected spike needs explaining.

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.

tokentrace mcp

Starts a local stdio MCP server so agents like Claude Code, Cursor, and Windsurf can connect TokenTrace as a Model Context Protocol tool. Startup is read-only and does not scan files, initialize the database, or open the dashboard, so an agent can discover the surface without side effects.

Registry name

The MCP server is published under io.github.abhiyoheswaran1/tokentrace. Agents resolve that name to TokenTrace's stdio entry point through the standard MCP registry contract.

get_agent_guide

The first MCP tool agents should call. Returns a structured guide to TokenTrace's privacy model, available tools, common workflows, and explicit guardrails (for example, that run_scan requires confirmLocalScan=true before any local file reads or database writes). Designed to ground an agent before it picks an action.

MCP tool surface

Beyond get_agent_guide, the server exposes get_status, run_doctor, get_evidence, get_repair_queue, and get_report as read-only tools, plus run_scan for explicit local ingestion. Agents pick the smallest tool that answers the question, and the read-only set never touches the local filesystem.

Agent-decisive response metadata

Every MCP response carries metadata an agent can act on without re-reading the dashboard: a summary, confidence, next actions, warnings, evidence hints, human-confirmation state, and the underlying payload. Agents decide deterministically whether to proceed or ask the human.

tokentrace mcp selftest --json

A non-invasive verification command that confirms the MCP server starts cleanly, advertises the expected tools, and matches the registry contract. The selftest does not scan files or read local CLI artifacts, so it is safe to run from CI or an onboarding script.

run_scan with confirmLocalScan

The run_scan MCP tool reads local CLI artifacts and writes to the local TokenTrace database, so it requires confirmLocalScan=true before it does anything. The flag is a deliberate, opt-in confirmation that the agent has surfaced the local-read step to a human first.

Resilient CLI help

Data-backed CLI help (agent guide, capabilities manifest, doctor, evidence) stays safe on a fresh install or a partially broken local database. The help surface never panics or leaks raw prompt bodies, so a freshly cloned environment still answers an agent's discovery call.

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

Structured usage logs

Native ingestion for the JSON and JSONL artifacts that Claude Code, Codex, OpenAI CLIs, and other AI tools already write on your machine. No wrapper required.

Cursor-style chat exports

Cursor and Cursor-format chat exports parse directly, so AI work that lives outside the standard CLI artifacts still lands in the same dashboard.

SQLite histories

TokenTrace reads native local SQLite history stores directly, alongside JSON and JSONL log artifacts. More data captured, fewer rows that fall through into simple estimates.

Source Coverage

Scan Health splits each scan into native, profile-assisted, fallback, and unsupported files, so it is obvious which sources are fully understood and which need attention.

Data Confidence

Each session and aggregate carries a Data Confidence score so a row of exact counts reads differently than a row of tokenizer estimates or a row of simple estimates. Mixed sources surface as a weighted score with the breakdown one click away.

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

Files checked

Every scan reports how many files were inspected, which Parsers ran, and how confident TokenTrace is in the result. The Parser Trust Report breaks the latest scan down by parser coverage; the Scan History Diff panel shows what changed between scans.

Parser warnings

Parsers that hit malformed records, unfamiliar shapes, or partial counts raise warnings inline. Each warning links to the affected files and the next action, so unknown counts never silently become zero.

Ignored support files

Telemetry sidecars, schema files, and other support artifacts are recognised and skipped on purpose. Scan Health lists what was ignored and why, so the count of "files I did not measure" stays explicit.

Cost coverage

Scan Health calls out the share of records with a matched Model Rate and the share without. The Insights pane translates the gap into the next concrete action (refresh rates, add an alias, review a parser).

Scan scheduling

Schedule scans on a cadence that matches your workflow: manual, on-open, hourly, or daily. The dashboard catches up to your local CLI usage without you remembering to run a command.

Supply-chain IOC checks

Scan Health flags Indicator-of-Compromise patterns inside ingested CLI artifacts. Suspicious shell history entries, leaked secrets in prompts, or known-bad command signatures surface alongside parser status, so accuracy and trust travel together.

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

Top cause

Overview metric cards link into the Repair workflow when cost coverage drops. Each row leads with its top cause: missing model, missing Model Rate, missing tokens, or other.

Next best repair

Each group surfaces the next best repair next to the evidence: an alias hint, a parser review link, or a Model Rate refresh. Bulk actions apply an alias across every matching row, refresh Model Rates for a whole provider, or dismiss a class of rows with a single decision.

What changes after repair

Before you commit a fix, the workflow shows what the totals will look like after the repair: which rows leave the unknown-cost queue, how cost coverage moves, and which Data Confidence labels upgrade.

Resolved, ignored, parser-review

Rows move through three explicit states. Resolved when an alias or Model Rate refresh fixes the cause, ignored when a class of rows is dismissed on purpose, parser-review when a parser warning needs a human look. The mix is visible at the top of the queue, so the workflow never silently buries an unknown.

Before / after delta

After a re-scan replays the affected rows through the updated Parsers and Model Rates, the Repair view shows a before/after delta and Scan History Diff records the movement so you can show your work. tokentrace repair --json prints the same grouped queue for scripting.

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

JSON or Markdown export

Export an Evidence Pack at any time. JSON for downstream tooling and agents, Markdown for human review. Same totals, same trail, in either format.

Totals and confidence drivers

Each pack includes the headline totals you see on Overview, plus the confidence drivers behind them: which sources contributed, which Parsers ran, where estimates were used and where exact counts were available.

Parser notes

Parser warnings, ignored support files, and unsupported records carry forward into the pack so the reader can audit the same decisions you made.

Model-rate state

Which Model Rates were in play, when they were last refreshed, and which records matched. Cost estimates always travel with their rate context.

No raw prompts by default

Evidence Packs do not include raw prompt or response bodies. Share local usage evidence with a teammate, a stakeholder, or an auditor without exporting the underlying conversation.

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.

tokentrace agent --json

A read-only discovery manifest describing TokenTrace's local-first privacy model, safe JSON commands, common workflows, Claude Code status-line setup, and guardrails (for example, never running tokentrace reset without explicit human approval). The discovery command does not scan files, initialize the database, or start the dashboard.

tokentrace capabilities --json

Alias for the agent discovery manifest. Use either depending on the agent's prompt. The structured capability surface is what MCP-aware agents call before they pick a command.

docs/agent-adoption.md, TOKENTRACE_AGENT.md, llms.txt

For agents that prefer file discovery, docs/agent-adoption.md walks through the MCP adoption flow, TOKENTRACE_AGENT.md primes the agent on TokenTrace's surface and guardrails, and llms.txt at the repo root indexes both for crawler-friendly retrieval.

/api/agent and /api/capabilities

When the dashboard is running, /api/agent and /api/capabilities return the same manifest over HTTP, so an agent that already has the dashboard open does not need to shell out to the CLI.

tokentrace roadmap --json

Returns the release status as structured data: shipped, in flight, deferred. Agents and external dashboards pull the same snapshot the maintainer ships against.

Trend aggregation, first-screen data, lazy Settings, plus mobile card layouts for Repair and Model Rates so the dashboard reads one-handed.

Trend aggregation

Token Trend and Cost Trend skip slow localtime bucketing, so weekly and monthly charts stay responsive even on a long history of sessions.

First-screen data

Overview loads the data the first screen needs first. Usage Pulse, the token accounting cards, and the headline trend chart paint before deeper trails resolve in the background.

Lazy Settings sections

Settings panels load on demand instead of all at once, so opening Settings, switching between Model Rates, Parsers, and Scan scheduling, or jumping back to Overview stays snappy as configuration grows.

Compact mobile navigation

Primary navigation tightens on narrow viewports, so the dashboard works one-handed without losing the surface you came in for.

Card layouts for Repair and Model Rates

The Repair workflow and Model Rates reflow into stacked cards under a breakpoint, so cost causes, alias hints, and rate state stay readable on a phone instead of forcing a horizontal scroll.

Denser Session Explorer filtering

Session Explorer filters condense on mobile so a recent-sessions sweep takes a tap rather than a zoom-and-scroll.

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

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 telemetry. Raw prompt and response bodies are not stored by default.

No billing, no accounts

TokenTrace does not charge users and does not require an account anywhere. Model Rates are only used to estimate provider costs in the local dashboard.

Model Rate refresh is the only network call

The only optional outbound network call fetches public Model Rate data so the local cost estimate stays accurate. Local files are never uploaded.

Inspectable runtime

The published package ships readable application source and the compiled CLI runtime, so anyone can inspect what actually runs on the machine. Releases include npm provenance attestations, so the code on npm matches the code in the public source repo.