toktrace

TokTrace is a lightweight Node.js token/cost tracker for LLM calls.

60-second quickstart (no app code changes)

npm install toktrace
npx toktrace install
npx toktrace run -- npm run dev
npx toktrace verify

That toktrace run command injects --import toktrace/auto so OpenAI/Anthropic/generic HTTP patching is enabled automatically.

Standard quickstart

npm install toktrace
npx toktrace init

Then either:

• Run your app with auto-instrumentation:

  npx toktrace run -- node server.js

• Or add one line in app startup:

  import { init } from "toktrace";
  init();

Dashboard

npx toktrace dashboard

Open http://localhost:4242.

No events yet? Seed sample data:

npx toktrace seed

What gets captured

• timestamp
• model/provider
• input/output/total tokens
• estimated cost
• latency
• prompt hash (full prompt body is not stored by default)
• environment tag
• tool call metadata (tool_call_count, serialized tool calls)

Importing from AI coding CLIs

Already using Claude Code? TokTrace can import every LLM call from your local session logs (no proxy, no key, no runtime injection):

toktrace import claude-code

Walks ~/.claude/projects/*/*.jsonl, upserts one event per assistant message with full token breakdown (input / output / cache-read / cache-creation) and cache-aware cost estimation. Re-runs are idempotent — safe to put on a cron. Events are tagged env=claude-code so you can filter or compare to your app-level LLM traffic.

Cost estimates for Claude Code Max subscribers are hypothetical pay-per-token numbers, useful for tracking usage volume and per-project burn but not your actual bill (which is flat).

Useful commands

• toktrace init — create local config + database.
• toktrace install — same as init, plus zero-code run instructions.
• toktrace run -- <command> — run any command with auto-instrumentation.
• toktrace verify — validate setup and first-event ingestion status.
• toktrace seed — insert sample events for instant dashboard preview.
• toktrace dashboard — launch local dashboard.
• toktrace import claude-code — import usage from Claude Code session logs.
• toktrace suggest — generate optimization suggestions.
• toktrace snapshot create --name "before" and toktrace snapshot export --name "before".