# TokenTrace

> Local-first analytics for AI CLI usage, focused on coding-agent tokens, costs, sessions, parser confidence, and evidence trails.

## Agent Entry Point

Start with:

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

Equivalent alias:

```bash
tokentrace capabilities --json
```

The manifest is read-only and follows `docs/agent-discovery.schema.json`.

MCP-capable clients can start TokenTrace over stdio:

```bash
tokentrace mcp
```

Registry name: `io.github.abhiyoheswaran1/tokentrace`.

Call `get_agent_guide` first in MCP clients. It returns the recommended
TokenTrace operating loop, install snippets, copy-paste AGENTS.md guidance, and
local-first guardrails.

Self-test without scanning files:

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

The MCP server does not scan on startup. Its `run_scan` tool requires
`confirmLocalScan=true` before reading local usage files or writing the local
database.

When the local dashboard is running, the same manifest is available at
`/api/agent` and `/api/capabilities`.

Roadmap status is available through `tokentrace roadmap --json` and
`/api/roadmap`.

## Useful Commands

- `tokentrace scan --json`: import local usage records.
- `tokentrace doctor --json`: inspect scan health, parser trust, support status, and repair recommendations.
- `tokentrace evidence --json`: trace aggregate numbers back to local sources.
- `tokentrace repair --json`: inspect unknown-cost repair work.
- `tokentrace digest --json`: summarize local usage.
- `tokentrace roadmap --json`: inspect the current release handoff, action recipes, evidence paths, and release status.
- `tokentrace mcp`: start the local stdio MCP server.
- `tokentrace mcp selftest --json`: verify MCP startup, tool listing, agent guide, and scan-confirmation refusal.
- `tokentrace statusline setup claude`: print Claude Code status-line setup.
- `tokentrace watch --session --compact`: terminal sidecar fallback for Codex.

## Guardrails

- Do not run `tokentrace reset` without explicit human approval.
- Do not describe processed tokens as current context size.
- Keep TokenTrace local-first: no telemetry, cloud sync, proxying, packet capture, or browser-extension path.
