trace ur token

Local-first trace intelligence for coding agents. It makes the invisible parts of working with Claude Code, Codex, and OpenCode inspectable: token burn, model usage, tool-call behavior, skill use, and probable instruction misses.

Product brief

Problem. Coding-agent transcripts contain a precise record of cost, behavior, and quality, but each provider stores it differently and none gives builders a cross-model accountability layer.

Audience. Individual builders and engineering teams who use more than one coding agent and want to reduce waste without uploading raw transcripts.

Core experience. One local command scans provider-owned trace directories, converts metadata into trace-token-report.json, and opens an expressive dashboard built around four questions: who used the tokens, what did they do, when do they work best, and where did they miss explicit instructions?

Principles. Local by default; normalized provider adapters; auditable heuristics instead of magic quality scores; no raw source, prompts, or transcripts leave the machine.

Architecture

Claude Code JSONL ─┐
Codex JSONL ───────┼─> source adapters -> normalizer -> heuristic analyzer -> portable report JSON
OpenCode JSON ─────┘                                              │
                                                               dashboard

• bin/trace-ur-token.mjs is the dependency-free command-line scanner.
• Each adapter discovers only known local transcript roots, then parses JSON/JSONL defensively.
• The normalizer aggregates model names, input/output tokens, tool/skill names, and session metadata.
• Heuristics flag suspected instruction misses only when constraint language coexists with dismissal signals. They are deliberately labelled signals rather than claims of truth.
• The dashboard is a single responsive TypeScript page. It is designed to accept the portable report format; the current initial UI includes a visual demo data set and file-import affordance.

Run it

npm install
npm run trace -- scan --output trace-token-report.json
npm run dev

For a global one-command release, publish this package under the trace-ur-token name; then the UX becomes:

npx trace-ur-token scan --serve

What the first release measures

• Total, input, and output tokens by model
• Tool calls, including skills where the provider exposes them
• Sessions, prompt volume, and activity timing
• Explicit constraints and suspected instruction misses
• Agent detours and repeated tool usage as cost-recovery signals

Next production increments

1. Make the dashboard hydrate from an imported report instead of the bundled demo.
2. Add fixture tests for every provider transcript shape and a transparent rule explorer for each heuristic.
3. Add a local SQLite history store for trend comparisons without ever centralizing traces.
4. Add an optional redacted team aggregate only after a clear consent and privacy model exists.