tokentrace

<p align="center">
  <img src="docs/assets/tokentrace-logo.svg" alt="TokenTrace logo" width="96" height="96">
</p>

# TokenTrace CLI

Local-first AI CLI usage analytics. TokenTrace scans local CLI logs and local usage databases, normalizes token usage, estimates missing counts with confidence labels, and shows cost, model, project, session, repair, and evidence analytics in a browser dashboard.

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](https://www.baseframelabs.com/apps/tokentrace) · [Source](https://github.com/abhiyoheswaran1/tokentrace)

![TokenTrace overview dashboard](docs/assets/overview-0.12.0.png)

## Start In Seconds

Run without installing:

```bash
npx tokentrace
```

Or install globally:

```bash
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:

```bash
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 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 <cmd>    # 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:

```bash
tokentrace agent --json
```

The alias below returns the same manifest:

```bash
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](TOKENTRACE_AGENT.md)
- [llms.txt](llms.txt)
- [docs/agent-adoption.md](docs/agent-adoption.md)
- [docs/agent-discovery.schema.json](docs/agent-discovery.schema.json)

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

```bash
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:

```bash
tokentrace mcp selftest --json
```

The MCP server exposes the same local-first surfaces as tools: capabilities,
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.

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

```bash
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:

```bash
tokentrace roadmap --json
curl http://127.0.0.1:3030/api/roadmap
```

## Run From Source

```bash
npm install
npm run db:migrate
npm run db:seed
npm run dev
```

Open `http://localhost:3000`.

Useful source commands:

```bash
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
```

## Local Sources And Trust

TokenTrace 0.12.0 bundles local source expansion, evidence exports, scan
scheduling, scoped guardrails, parser profile preview, saved reports, and
agent-readable release status.

New 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

The 0.12.0 dashboard also tightens the daily operator path: setup buttons now
open the exact Settings section, scan results show what changed and where to go
next, and Evidence explains when it is being opened as a contextual drill-down
rather than a sidebar destination.

## 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 Overview, 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](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:

```bash
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:

```bash
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** in the dashboard 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 Overview 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 spike