Claude Code plugin · MIT · zero dependencies
tokenomics
The token economy of every session — made visible, attributable, and provable.
A session spends two scarce resources at once: the context window and dollars. tokenomics reads your transcript offline and turns both into exact numbers, attribution, and advice you can prove with an eval.
01 The problem
Two budgets, both invisible until they break.
A Claude Code session burns context-window tokens — which quietly degrade quality as the window fills (attention budget, context rot) — and dollars, the same tokens priced. Both stay hidden in-session until the model gets vague near the cliff, or the monthly bill surprises you.
Every other usage tool is a passive display: it shows the number and stops. tokenomics attributes the spend to the model, subagent, tool, and skill that caused it — then closes the loop with advice you can measure.
02 Install
One command. Zero config.
Then run /tokenomics in any session. That is the whole zero-config path — it reads the current session's transcript and prints the report.
Optional: the live HUD
Add one line to settings.json for a context + cost gauge in your prompt:
███████░░░ 73% · $0.4200 · Opus 4.8 ◔ tight
03 Commands
Six verbs over one transcript.
reportCost, a context gauge, attribution by model and channel, top context consumers, and the top recommendations. The default.
attributeThe breakdown only — cost and context by model, subagent, tool, and skill.
adviseRanked recommendations, each carrying a prove it eval command.
routeRouting advice; route --scaffold <name> --model haiku writes a cost-routed subagent preset.
evalProve a delta — --before a.jsonl --after b.jsonl returns the token/$ saved and a verdict.
models--check <id> shows how a model is priced: exact, by family pattern, or conservative default.
04 How it works
Exact, offline, from the transcript.
Claude Code writes a per-session transcript with an exact usage object on every turn. tokenomics streams that file and computes cost with correct cache-tier math — cache read 0.1×, 5-minute write 1.25×, 1-hour write 2× — plus web-search add-ons and batch / data-residency modifiers. Output already includes thinking, so it is never double-counted.
Attribution uses isSidechain to separate subagents from the main loop, and joins tool calls to their results. No network calls, no telemetry, nothing stored about you.
05 What it won't do
Honesty over a flashy claim.
Silent model switching
Claude Code doesn't let a plugin reroute the live model. Routing is delivered as advice plus static subagent presets you opt into — never a surprise swap.
Forced compaction
A plugin can't trigger compaction, only observe it. tokenomics warns and suggests /compact — it never compacts behind your back.
Network calls
Everything is computed locally from the transcript. No telemetry, no account linkage, no third-party runtime dependencies to trust.
06 Future-proof pricing
New models price themselves.
Pricing lives as data with family-prefix patterns, so a returning or brand-new model is priced with zero code change. A genuinely unknown id is flagged, never guessed silently.
07 Security posture
A surface this small is the point.
Zero dependencies
Pure Node standard library. No supply chain to audit, nothing to compromise.
Read-only & offline
Reads transcripts, writes only its own report and state. No eval, no child_process, no network.
Hardened
Adversarially audited: path-traversal-safe hooks, sanitized inputs, a parse guard against hostile transcripts.