\n\n# TokenTrace CLI\n\nLocal-first AI CLI usage analytics for developers and coding agents.\n\nTokenTrace answers one practical question before the next expensive AI CLI run:\nis your local usage evidence ready to trust? It scans local Claude Code, Codex,\nstructured usage logs, and usage-shaped local databases, then labels token and\ncost data as exact, estimated, unknown, cached, or non-cache. The dashboard\nopens on **Today**, with direct paths into Sessions, Evidence, and Fix Data.\n\nTokenTrace 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.\n\n[Website](https://www.baseframelabs.com/apps/tokentrace) · [Source](https://github.com/abhiyoheswaran1/tokentrace)\n\n\n\n## What TokenTrace Helps You Do\n\n- Check readiness before another coding-agent run with `tokentrace preflight --json` or MCP `get_preflight`.\n- See today’s local cost, tokens, sessions, confidence, anomalies, and repair signals in one first screen.\n- Trace every important number back to local files, parser state, sessions, model rates, and confidence labels.\n- Fix missing cost data through a guided repair queue without uploading prompts or message bodies.\n\n## Start In Seconds\n\nRun without installing:\n\n```bash\nnpx tokentrace\n```\n\nOr install globally:\n\n```bash\nnpm install -g tokentrace\ntokentrace\n```\n\nThe 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`.\n\nCLI commands:\n\n```bash\ntokentrace # Start local dashboard\ntokentrace serve # Start local dashboard\ntokentrace serve --port 3210 --no-open\n # Start on a fixed port without opening a browser\ntokentrace agent --json # Print machine-readable agent discovery manifest\ntokentrace capabilities --json\n # Alias for agent discovery manifest\ntokentrace roadmap --json\n # Print release status handoff\ntokentrace mcp # Start the local stdio MCP server\ntokentrace scan # Scan local AI CLI usage logs\ntokentrace doctor --json\n # Inspect scan health and repair recommendations\ntokentrace preflight --json\n # Check readiness before another coding-agent run\ntokentrace evidence --json\n # Print metric evidence trails as JSON\ntokentrace repair --json\n # Print unknown-cost repair groups as JSON\ntokentrace digest --json\n # Print current-month local usage digest\ntokentrace digest --since yesterday\n # Print a scoped local usage digest\ntokentrace report --markdown\n # Print a deterministic Markdown report\ntokentrace review --json\n # Print post-session scan and review movement\ntokentrace insights --json\n # Print local recommendations as JSON\ntokentrace status --json\n # Print local usage status as JSON\ntokentrace statusline claude\n # Render a Claude Code status line from stdin\ntokentrace statusline claude --compact\n # Render a shorter Claude Code status line\ntokentrace statusline setup claude\n # Print Claude Code statusLine setup JSON\ntokentrace watch --session\n # Watch local usage status in a terminal split\ntokentrace watch --session --compact\n # Watch a compact live status line\ntokentrace pricing refresh\n # Refresh public model prices\ntokentrace run # Optional wrapper mode for command runtime diagnostics\ntokentrace reset # Reset imported local data\ntokentrace reset --yes # Reset without confirmation\ntokentrace --help # Print help\ntokentrace --version # Print version\n```\n\n## For Coding Agents\n\nAgents should start with the read-only discovery manifest:\n\n```bash\ntokentrace agent --json\n```\n\nThe alias below returns the same manifest:\n\n```bash\ntokentrace capabilities --json\n```\n\nThe manifest describes TokenTrace's local-first privacy model, safe JSON commands,\ncommon workflows, Claude Code status-line setup, Codex sidecar fallback, and\nguardrails such as never running `tokentrace reset` without explicit human\napproval. The discovery command does not scan files, initialize the database, or\nstart the dashboard.\n\nPackage-level agent references are included for agents that inspect repository\nor npm package contents before invoking commands:\n\n- [TOKENTRACE_AGENT.md](TOKENTRACE_AGENT.md)\n- [llms.txt](llms.txt)\n- [docs/agent-adoption.md](docs/agent-adoption.md)\n- [docs/agent-discovery.schema.json](docs/agent-discovery.schema.json)\n\nMCP-capable clients can start the local stdio server after installing or using\nthe npm package:\n\n```bash\ntokentrace mcp\n```\n\nRegistry name: `io.github.abhiyoheswaran1/tokentrace`.\n\nFirst MCP call for agents: `get_agent_guide`.\n\nSelf-test the local MCP entrypoint without scanning files:\n\n```bash\ntokentrace mcp selftest --json\n```\n\nThe MCP server exposes the same local-first surfaces as tools: capabilities,\npreflight, status, Scan Health, evidence, repair queue, reports, and an\nexplicit scan tool. It does not scan files on startup, and its scan tool requires\n`confirmLocalScan=true` before reading local usage files or writing the local\ndatabase.\n\nBefore starting another long coding-agent run, use preflight:\n\n```bash\ntokentrace preflight --json\n```\n\nIn MCP clients, call `get_preflight` for the same proceed, caution, or blocked\ndecision with local scan freshness, confidence, guardrail, anomaly, and repair\nfindings. Preflight does not scan files or inspect raw prompts.\n\nWhen the local dashboard is already running, agents can fetch the same manifest\nover localhost:\n\n```bash\ncurl http://127.0.0.1:3030/api/agent\ncurl http://127.0.0.1:3030/api/capabilities\n```\n\nThe Local Sources & Trust release handoff is also machine-readable:\n\n```bash\ntokentrace roadmap --json\ncurl http://127.0.0.1:3030/api/roadmap\n```\n\n## Run From Source\n\n```bash\nnpm install\nnpm run db:migrate\nnpm run db:seed\nnpm run dev\n```\n\nOpen `http://localhost:3000`.\n\nUseful source commands:\n\n```bash\nnpm run dev # Start the Next.js dev server\nnpm run build # Build the production app\nnpm run start # Serve the production build\nnpm run scan # Scan default and configured folders\nnpm run db:migrate # Create/update local SQLite tables\nnpm run db:seed # Seed editable provider/model prices\nnpm run screenshots:seed\n # Seed a guarded public-safe screenshot database\nnpm run reset # Clear imported data and scan history\nnpm test # Run parser and cost tests\nnpm run verify # Run Vitest, TypeScript, and ESLint checks\nnpm run package:test # Verify, build, and dry-run the npm package\nnpm run package:inspect\n # Check package transparency guardrails\nnpm run security:ioc\n # Scan lockfiles, workflows, and local AI-tool hooks for supply-chain IOCs\nnpm run smoke:packed\n # Inspect packed tarball and smoke test packed CLI\ntokentrace roadmap --json\n # Inspect roadmap handoff, action recipes, and release status\n```\n\n## Daily Loop And Trust\n\nTokenTrace now organizes the product around the daily loop:\n\n1. **Preflight**: decide whether local evidence is ready before another agent run.\n2. **Today**: review cost, token, session, confidence, anomaly, and repair signals.\n3. **Evidence**: trace numbers back to source files, parser confidence, sessions, and model-rate state.\n4. **Fix Data**: resolve unknown cost, parser review, and model-rate gaps.\n5. **Advanced**: inspect Scan Health, Discovery, Parsers, Raw Data, Query, and Model Rates when you need the full diagnostic surface.\n\nTrust surfaces include:\n\n- native structured usage log and Cursor-style chat export ingestion\n- Source Coverage in Scan Health for native, profile-assisted, fallback, and\n unsupported files\n- privacy-safe Evidence Packs as JSON or Markdown\n- local scan scheduling: manual, on-open, hourly, or daily\n- project/model/tool scoped guardrails with warning thresholds\n- Import Profile preview before saving matchers\n- saved report exports for weekly usage, source coverage, guardrails, unknown\n cost, high-cost sessions, and confidence trends\n- operating metadata export without raw usage records\n\n## Accuracy And Evidence\n\nTokenTrace labels the trust level behind imported numbers:\n\n- exact provider token counts\n- tokenizer estimates for recognized OpenAI/Codex and Claude-family model names\n- simple estimates when only text-like content is available\n- source-provided costs from local SQLite histories\n- unknown cost repair groups when model, token, or rate evidence is missing\n\nThe dashboard surfaces a Data Confidence score on Today, Projects, Sessions,\nand Session Timeline pages. Scan Health also includes a supply-chain IOC check\nso package trust is visible in the product, not only in release scripts.\n\nPublic releases require maintainer approval. See\n[docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md) before bumping versions,\ntagging, creating GitHub releases, or publishing npm.\n\nIn local development, the SQLite database defaults to `.tokentrace/tokentrace.db`. Override it with:\n\n```bash\nTOKENTRACE_DB=/absolute/path/tokentrace.db npm run dev\n```\n\n## Data Location\n\nWhen installed from npm, TokenTrace stores runtime data outside the package folder:\n\n- macOS: `~/Library/Application Support/TokenTrace/`\n- Linux: `~/.local/share/tokentrace/`\n- Windows: `%APPDATA%/TokenTrace/`\n\nThe CLI sets `TOKENTRACE_DB` and `DATABASE_URL` automatically. You can override the base directory with:\n\n```bash\nTOKENTRACE_HOME=/custom/path tokentrace\n```\n\n## Where TokenTrace Looks\n\nDefault discovery checks these locations when present:\n\n- `~/.claude/`\n- `~/.config/claude/`\n- `~/.codex/`\n- `~/.config/codex/`\n- `~/.openai/`\n- Project-level hidden folders such as `.claude`, `.codex`, `.openai`, and `.ai` in the directory where `tokentrace` was invoked\n- TokenTrace wrapper logs in the local app-data directory\n- Any custom folders configured in Settings\n\nUse **Settings** to add custom folders, toggle raw message storage, and trigger\nscans. Use **Scan Health**, **Discovery**, **Parsers**, and **Raw Data** to\ninspect discovered files, parser decisions, warnings, failures, extracted\nmetadata, and confidence levels.\n\nSettings also supports optional local monthly usage guardrails. Set a cost\nlimit, token limit, or both, and Today will show month-to-date progress from\nimported local CLI usage.\n\nSessions includes built-in and local saved views for recurring review paths:\nunknown cost, high-cost sessions, Claude/Codex this month, estimated tokens,\nguardrail review, and parser review. Open a session's **Timeline** link to see\nordered interactions, model changes, token spikes, cache activity, tool calls,\nparser confidence, and unknown-cost events. Raw prompts and message bodies stay\nhidden by default.\n\n## Ingestion Architecture\n\nTokenTrace's primary ingestion architecture is direct local filesystem ingestion:\n\n1. Discover local AI CLI artifacts.\n2. Parse supported formats through adapters.\n3. Normalize sessions, interactions, token usage, models, projects, and tool calls.\n4. Store normalized records locally in SQLite.\n5. Visualize analytics in the local dashboard.\n\nTokenTrace does not use MITM proxies, packet sniffing, browser extensions, traffic interception, or cloud telemetry.\n\nEach adapter detects compatibility, parses partial metadata where possible, and fails safely when a file format is unsupported. Imported interactions carry token confidence metadata:\n\n- `exact`\n- `high-confidence estimate`\n- `low-confidence estimate`\n- `unknown`\n\nExact and estimated token values are never mixed silently.\n\n## Optional Wrapper Mode\n\nFilesystem ingestion is the primary product path. Wrapper mode is secondary and optional:\n\n```bash\ntokentrace run claude-code\ntokentrace run codex\ntokentrace run npm test\n```\n\nWrapper mode launches the subprocess, measures duration, counts stdout/stderr bytes, detects structured JSON output when available, and writes a local JSONL diagnostic log under the app-data directory. It does not intercept network traffic.\n\n## Claude Code Status Line\n\nClaude Code can run a local status-line command at the bottom of its terminal UI. TokenTrace supports that path directly:\n\n```bash\ntokentrace statusline setup claude\n```\n\nAdd the printed `statusLine` block to `~/.claude/settings.json`. It points Claude Code at:\n\n```bash\ntokentrace statusline claude\n```\n\nClaude Code sends session JSON to the command on stdin. TokenTrace reads the transcript path, model, context usage, and session cost, then prints one compact local line:\n\n```text\nTokenTrace | Opus | ctx 7% | cost $0.1235 | processed 3.3K tokens | cache 2.0K | priced\n```\n\nDo not set the Claude Code `statusLine.command` to plain `tokentrace`. Plain `tokentrace` starts the dashboard, while `tokentrace statusline claude` prints exactly one status-line response.\n\n\n\nYou can also inspect the same local status outside Claude Code:\n\n```bash\ntokentrace status --json\ntokentrace watch --session\n```\n\nDaily reporting commands stay deterministic and local:\n\n```bash\ntokentrace digest --since last-scan\ntokentrace digest --since 2026-05-01 --json\ntokentrace report --markdown --since yesterday\ntokentrace review --json\n```\n\nCodex CLI status-line integration is intentionally deferred until its status-line and hook contracts are stable enough to support without fragile terminal output parsing. Use `tokentrace watch --session --compact` in a terminal split or tmux pane as the current fallback. See [docs/CODEX_INTEGRATION_SPIKE.md](docs/CODEX_INTEGRATION_SPIKE.md) for the current decision.\n\n## Screenshots\n\nDashboard views:\n\n\n\n\n\n\n\n\n\nCLI startup and help:\n\n\n\nLocal scan output:\n\n\n\nOptional wrapper diagnostics:\n\n\n\n## Privacy Model\n\n- All processing runs locally on your machine.\n- No external telemetry is included. Next.js telemetry is disabled by the CLI.\n- No cloud account is required.\n- Raw full prompts and responses are not stored by default.\n- TokenTrace stores short text previews for debugging and analytics context.\n- TokenTrace may download a public model-pricing manifest so cost estimates stay useful. It does not send usage logs, prompts, file paths, or analytics data with that request. Set `TOKENTRACE_DISABLE_PRICE_REFRESH=1` to use only bundled prices.\n- Turn on **Store raw message content** in Settings only if you want full local message text preserved in SQLite.\n\nStop the server with `Ctrl+C` in the terminal where `tokentrace` is running.\n\n## Package Trust\n\n- The TokenTrace npm package has no `preinstall`, `install`, or `postinstall` scripts.\n- The published package ships readable application source and the compiled CLI runtime, not generated `.next/server` route bundles.\n- `tokentrace serve` prepares the local dashboard build in the user's TokenTrace app-data directory the first time it is needed.\n- `npm run package:inspect` fails if generated Next.js build output appears in the published tarball.\n- `npm run security:ioc` scans lockfiles, workflows, and local Claude/VS Code hook files for high-signal supply-chain compromise indicators.\n- Public npm publishing is configured through GitHub Actions Trusted Publishing and provenance from version tags.\n- Socket GitHub checks and ProjScan are used as release guardrails, alongside `npm audit --audit-level=moderate`.\n- `npm run release:check` fails when a gate command exits non-zero. The import graph is expected to remain free of circular dependencies; `tests/import-boundaries.test.ts` protects shared type/helper modules from importing higher-level orchestration barrels.\n- Release notes are published directly in GitHub Releases from the relevant changelog section, not as a link-only summary.\n\nSee [SECURITY.md](SECURITY.md) for the full security and privacy model.\n\n## Model Rates\n\nModel prices change. TokenTrace ships with bundled public list prices and can refresh them from a public TokenTrace model-rate manifest. Manual edits made in **Model Rates** are preserved by future refreshes.\n\nThe bundled catalog includes common OpenAI, Anthropic, Google Gemini, xAI, DeepSeek, Mistral, and Cohere models, checked on May 8, 2026.\n\nSeed sources:\n\n- [OpenAI API pricing](https://openai.com/api/pricing/) and [OpenAI model docs](https://developers.openai.com/api/docs/models)\n- [Anthropic Claude pricing](https://platform.claude.com/docs/en/about-claude/pricing)\n- [Gemini Developer API pricing](https://ai.google.dev/gemini-api/docs/pricing)\n- [xAI models and pricing](https://docs.x.ai/developers/models)\n- [DeepSeek models and pricing](https://api-docs.deepseek.com/quick_start/pricing)\n- [Mistral model docs](https://docs.mistral.ai/models)\n- [Cohere pricing](https://cohere.com/pricing)\n\nReview and update rates in **Model Rates** before treating cost estimates as financial truth, especially if you use batch processing, priority/flex modes, data residency, long-context surcharges, subscriptions, or provider-specific discounts.\n\nRefresh from the dashboard or from the CLI:\n\n```bash\ntokentrace pricing refresh\n```\n\nCost is calculated per interaction:\n\n```text\ninputTokens * inputPricePer1M / 1,000,000\n+ outputTokens * outputPricePer1M / 1,000,000\n+ cacheReadTokens * cachedInputPricePer1M / 1,000,000\n+ cacheWriteTokens * cacheWritePricePer1M / 1,000,000\n```\n\nCache read and cache write prices fall back to input price when a model has no separate cache rate. Anthropic seed rows use the 5-minute prompt cache write price by default. Rows are marked exact, estimated, or unknown depending on token availability and pricing configuration.\n\n## Supported Inputs\n\nAdapters live under `src/ingestion/adapters/`:\n\n- `claude-code.ts`\n- `codex-cli.ts`\n- `structured-usage-log.ts`\n- `cursor-chat.ts`\n- `sqlite-history.ts`\n- `generic-jsonl.ts`\n- `generic-json.ts`\n- `generic-log.ts`\n\nFormats for Claude Code and Codex CLI can vary across versions, so these adapters are defensive and best-effort. Unknown files fail safely and show warnings in the Raw Data page.\n\n## Support Matrix\n\nTokenTrace keeps a visible support contract so daily scans are easier to trust:\n\n| Surface | Support level | Notes |\n| --- | --- | --- |\n| Claude Code project transcripts | Stable | Primary local CLI ingestion source. |\n| Codex CLI session artifacts | Best-effort | Parsed defensively while CLI formats evolve. |\n| Structured usage JSONL/NDJSON | Stable | Local wrapper and team logs with session, model, token, and source-cost fields. |\n| Cursor-style chat exports | Best-effort | Imports local editor chat/composer exports without storing raw prompt text by default. |\n| Usage-shaped SQLite histories | Best-effort | Reads local databases that expose session, model, token, or cost-like columns. |\n| Generic JSONL, JSON, and text logs | Best-effort | Conservative usage-shaped records only. |\n| Claude/Codex cache, plugin, todo, config, and support files | Ignored | Tracked as non-usage files, not parser failures. |\n| Editable model pricing | Stable | Local pricing rows drive costs and unknown-cost repair queues. |\n| Claude Code status line | Stable | Uses Claude Code's documented statusLine stdin contract. |\n| Codex sticky status line | Best-effort fallback | Use `tokentrace watch --session --compact` in a split or tmux pane. |\n| Desktop app scraping, browser extensions, proxying, packet capture, telemetry | Unsupported | Outside TokenTrace's product boundary. |\n\n## Extending Parsers\n\nExample generic JSONL fixtures are in `fixtures/generic-jsonl/`.\n\nThe ingestion system is intentionally pluggable:\n\n1. Add an adapter implementing `IngestionAdapter`.\n2. Register it in `src/ingestion/adapters/index.ts`.\n3. Add parser tests under `tests/`.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, parser guidelines, pricing update notes, and the release policy.\n\n## Troubleshooting\n\n### `prebuild-install` deprecation warning during install\n\n```\nnpm warn deprecated prebuild-install@7.1.3: No longer maintained...\n```\n\nThis is a transitive dependency of `better-sqlite3` (the native SQLite driver TokenTrace uses to store local data). The warning is harmless — the install completes normally and TokenTrace runs as expected. It will go away once `better-sqlite3` upstream migrates to a different prebuilt binary loader; there is nothing to fix on the TokenTrace side.\n\n### Native build errors on `better-sqlite3`\n\nIf the prebuilt binary cannot be downloaded (offline machine, restrictive proxy, unsupported Node ABI), `better-sqlite3` will try to compile from source and may fail. Workarounds:\n\n- Ensure Node.js is a supported LTS (TokenTrace requires `>= 20.0.0`; Node 20 or 22 LTS is recommended).\n- Install build tools: Xcode Command Line Tools on macOS, `build-essential` and `python3` on Linux, or the \"Desktop development with C++\" workload on Windows.\n- Retry the install with network access to `github.com` so the prebuilt binary can be fetched.\n\n### `EBADENGINE` warnings\n\nThese appear when your local Node version is older than the `engines` field of a transitive dependency. They are warnings, not errors. Upgrading to the latest Node LTS resolves them.\n\n## Known Limitations\n\n- Claude Code and Codex CLI log formats are inferred defensively and may need refinement with real sample logs.\n- Tokenizer-backed estimates are available for recognized OpenAI/Codex and Claude-family model names. Unrecognized text-only records still fall back to a conservative simple estimate.\n- SQLite-history ingestion expects usage-shaped local tables and skips arbitrary databases that do not expose session, model, token, or cost-like fields.\n- Seed prices are editable and should be verified manually for your account, region, and provider plan.\n\n## License\n\nOpen source by [Abhi Yoheswaran](https://www.abhiyoheswaran.com). Released under the MIT License. See `LICENSE`.\n\n## Next Improvements\n\n- Expand first-class native adapters for more local AI tools and editor histories.\n- Add provider-specific tokenizer refinements where public tokenizer behavior is stable enough to label clearly.\n- Make Import Profile preview more interactive for teams with custom wrapper logs.\n- Stream scan progress into the UI for very large local folders.\n",
"bytes": 23129,
"sha": "f16e05be30bd78c29096077cc1e7c7401cb9c9fa73848f1dcdd5b433202ecd46",
"repo_slug": "abhiyoheswaran1/tokentrace",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_abhiyoheswaran1_tokentrace_7ee83939/readme"
}
![\"TokenTrace](\"docs/assets/tokentrace-logo.svg\"){kind=logo}
\n