TokenTrace

TokenTrace CLI

Local-first AI CLI usage analytics for developers and coding agents.

TokenTrace answers one practical question before the next expensive AI CLI run: is your local usage evidence ready to trust? It scans local Claude Code, Codex, structured usage logs, and usage-shaped local databases, then labels token and cost data as exact, estimated, unknown, cached, or non-cache. The dashboard opens on Today, with direct paths into Sessions, Evidence, and Fix Data.

TokenTrace is designed for local development machines first, with macOS-oriented defaults. It does not require a cloud account and does not send telemetry or logs anywhere.

Website · Source

What TokenTrace Helps You Do

• Check readiness before another coding-agent run with tokentrace preflight --json or MCP get_preflight.
• See today’s local cost, tokens, sessions, confidence, anomalies, and repair signals in one first screen.
• Trace every important number back to local files, parser state, sessions, model rates, and confidence labels.
• Fix missing cost data through a guided repair queue without uploading prompts or message bodies.

Start In Seconds

Run without installing:

npx tokentrace

Or install globally:

npm install -g tokentrace

tokentrace

The command starts the local dashboard, chooses an available localhost port starting at 3030, opens your default browser, and keeps the server running until you press Ctrl+C.

CLI commands:

tokentrace              # Start local dashboard

tokentrace serve # Start local dashboard tokentrace serve --port 3210 --no-open

Start on a fixed port without opening a browser

tokentrace agent --json # Print machine-readable agent discovery manifest tokentrace capabilities --json

Alias for agent discovery manifest

tokentrace roadmap --json

Print release status handoff

tokentrace mcp # Start the local stdio MCP server tokentrace scan # Scan local AI CLI usage logs tokentrace doctor --json

Inspect scan health and repair recommendations

tokentrace preflight --json

Check readiness before another coding-agent run

tokentrace evidence --json

Print metric evidence trails as JSON

tokentrace repair --json

Print unknown-cost repair groups as JSON

tokentrace digest --json

Print current-month local usage digest

tokentrace digest --since yesterday

Print a scoped local usage digest

tokentrace report --markdown

Print a deterministic Markdown report

tokentrace review --json

Print post-session scan and review movement

tokentrace insights --json

Print local recommendations as JSON

tokentrace status --json

Print local usage status as JSON

tokentrace statusline claude

Render a Claude Code status line from stdin

tokentrace statusline claude --compact

Render a shorter Claude Code status line

tokentrace statusline setup claude

Print Claude Code statusLine setup JSON

tokentrace watch --session

Watch local usage status in a terminal split

tokentrace watch --session --compact

Watch a compact live status line

tokentrace pricing refresh

Refresh public model prices

tokentrace run # Optional wrapper mode for command runtime diagnostics tokentrace reset # Reset imported local data tokentrace reset --yes # Reset without confirmation tokentrace --help # Print help tokentrace --version # Print version

For Coding Agents

Agents should start with the read-only discovery manifest:

tokentrace agent --json

The alias below returns the same manifest:

tokentrace capabilities --json

The manifest describes TokenTrace's local-first privacy model, safe JSON commands, common workflows, Claude Code status-line setup, Codex sidecar fallback, and guardrails such as never running tokentrace reset without explicit human approval. The discovery command does not scan files, initialize the database, or start the dashboard.

Package-level agent references are included for agents that inspect repository or npm package contents before invoking commands:

• TOKENTRACE_AGENT.md
• llms.txt
• docs/agent-adoption.md
• docs/agent-discovery.schema.json

MCP-capable clients can start the local stdio server after installing or using the npm package:

tokentrace mcp

Registry name: io.github.abhiyoheswaran1/tokentrace.

First MCP call for agents: get_agent_guide.

Self-test the local MCP entrypoint without scanning files:

tokentrace mcp selftest --json

The MCP server exposes the same local-first surfaces as tools: capabilities, preflight, status, Scan Health, evidence, repair queue, reports, and an explicit scan tool. It does not scan files on startup, and its scan tool requires confirmLocalScan=true before reading local usage files or writing the local database.

Before starting another long coding-agent run, use preflight:

tokentrace preflight --json

In MCP clients, call get_preflight for the same proceed, caution, or blocked decision with local scan freshness, confidence, guardrail, anomaly, and repair findings. Preflight does not scan files or inspect raw prompts.

When the local dashboard is already running, agents can fetch the same manifest over localhost:

curl http://127.0.0.1:3030/api/agent

curl http://127.0.0.1:3030/api/capabilities

The Local Sources & Trust release handoff is also machine-readable:

tokentrace roadmap --json

curl http://127.0.0.1:3030/api/roadmap

Run From Source

npm install

npm run db:migrate npm run db:seed npm run dev

Open http://localhost:3000.

Useful source commands:

npm run dev          # Start the Next.js dev server

npm run build # Build the production app npm run start # Serve the production build npm run scan # Scan default and configured folders npm run db:migrate # Create/update local SQLite tables npm run db:seed # Seed editable provider/model prices npm run screenshots:seed

Seed a guarded public-safe screenshot database

npm run reset # Clear imported data and scan history npm test # Run parser and cost tests npm run verify # Run Vitest, TypeScript, and ESLint checks npm run package:test # Verify, build, and dry-run the npm package npm run package:inspect

Check package transparency guardrails

npm run security:ioc

Scan lockfiles, workflows, and local AI-tool hooks for supply-chain IOCs

npm run smoke:packed

Inspect packed tarball and smoke test packed CLI

tokentrace roadmap --json

Inspect roadmap handoff, action recipes, and release status

Daily Loop And Trust

TokenTrace now organizes the product around the daily loop:

1. Preflight: decide whether local evidence is ready before another agent run.
2. Today: review cost, token, session, confidence, anomaly, and repair signals.
3. Evidence: trace numbers back to source files, parser confidence, sessions, and model-rate state.
4. Fix Data: resolve unknown cost, parser review, and model-rate gaps.
5. Advanced: inspect Scan Health, Discovery, Parsers, Raw Data, Query, and Model Rates when you need the full diagnostic surface.

Trust surfaces include:

• native structured usage log and Cursor-style chat export ingestion
• Source Coverage in Scan Health for native, profile-assisted, fallback, and unsupported files
• privacy-safe Evidence Packs as JSON or Markdown
• local scan scheduling: manual, on-open, hourly, or daily
• project/model/tool scoped guardrails with warning thresholds
• Import Profile preview before saving matchers
• saved report exports for weekly usage, source coverage, guardrails, unknown cost, high-cost sessions, and confidence trends
• operating metadata export without raw usage records

Accuracy And Evidence

TokenTrace labels the trust level behind imported numbers:

• exact provider token counts
• tokenizer estimates for recognized OpenAI/Codex and Claude-family model names
• simple estimates when only text-like content is available
• source-provided costs from local SQLite histories
• unknown cost repair groups when model, token, or rate evidence is missing

The dashboard surfaces a Data Confidence score on Today, Projects, Sessions, and Session Timeline pages. Scan Health also includes a supply-chain IOC check so package trust is visible in the product, not only in release scripts.

Public releases require maintainer approval. See docs/RELEASE_CHECKLIST.md before bumping versions, tagging, creating GitHub releases, or publishing npm.

In local development, the SQLite database defaults to .tokentrace/tokentrace.db. Override it with:

TOKENTRACE_DB=/absolute/path/tokentrace.db npm run dev

Data Location

When installed from npm, TokenTrace stores runtime data outside the package folder:

• macOS: ~/Library/Application Support/TokenTrace/
• Linux: ~/.local/share/tokentrace/
• Windows: %APPDATA%/TokenTrace/

The CLI sets TOKENTRACE_DB and DATABASE_URL automatically. You can override the base directory with:

TOKENTRACE_HOME=/custom/path tokentrace

Where TokenTrace Looks

Default discovery checks these locations when present:

• ~/.claude/
• ~/.config/claude/
• ~/.codex/
• ~/.config/codex/
• ~/.openai/
• Project-level hidden folders such as .claude, .codex, .openai, and .ai in the directory where tokentrace was invoked
• TokenTrace wrapper logs in the local app-data directory
• Any custom folders configured in Settings

Use Settings to add custom folders, toggle raw message storage, and trigger scans. Use Scan Health, Discovery, Parsers, and Raw Data to inspect discovered files, parser decisions, warnings, failures, extracted metadata, and confidence levels.

Settings also supports optional local monthly usage guardrails. Set a cost limit, token limit, or both, and Today will show month-to-date progress from imported local CLI usage.

Sessions includes built-in and local saved views for recurring review paths: unknown cost, high-cost sessions, Claude/Codex this month, estimated tokens, guardrail review, and parser review. Open a session's Timeline link to see ordered interactions, model changes, token spikes, cache activity, tool calls, parser confidence, and unknown-cost events. Raw prompts and message bodies stay hidden by default.

Ingestion Architecture

TokenTrace's primary ingestion architecture is direct local filesystem ingestion:

1. Discover local AI CLI artifacts.
2. Parse supported formats through adapters.
3. Normalize sessions, interactions, token usage, models, projects, and tool calls.
4. Store normalized records locally in SQLite.
5. Visualize analytics in the local dashboard.

TokenTrace does not use MITM proxies, packet sniffing, browser extensions, traffic interception, or cloud telemetry.

Each adapter detects compatibility, parses partial metadata where possible, and fails safely when a file format is unsupported. Imported interactions carry token confidence metadata:

• exact
• high-confidence estimate
• `lo