ccusage vs token-optimizer: two dashboards, one independent

Part of the reduce Claude Code token usage pillar. This is the only pair here where both tools report numbers, and the difference is who they answer to.

Is ccusage or token-optimizer what I need?

Both, and for a reason that is not about features: one of them is measuring its own effect. token-optimizer's dashboard is genuinely richer — per-turn costs, model mix, cache analysis, subagent breakdown, skill adoption, drift detection. ccusage gives you daily and weekly totals, a per-model split, cache tokens and a 5-hour billing block view, and nothing else. But token-optimizer also changes your sessions. A tool that both optimises and reports is the one case where an independent second reading is worth the two minutes it costs. That is not a suspicion about this project specifically; it is how you would treat any instrument attached to the thing it measures. I maintain an open long-session benchmark and sell a competing tool. token-optimizer has not been measured on it, so its dashboard is currently the only public account of its own effect.

What does ccusage actually do?

It reads your agent's local JSONL transcripts and reports what you spent. Roughly 15k stars, 15 supported agent sources, zero install — bunx ccusage or npx ccusage@latest. Daily, weekly, monthly and per-session reports, per-model breakdown, cache token tracking, and JSON output that composes with other dashboards. Its two structural properties matter here more than its features. It is read-only, so it cannot influence what it reports. And it is agent-agnostic across 15 sources, so it gives you one number across a mixed setup rather than one number per tool. Its limits are stated: it reduces nothing, it has no counterfactual, and the JSONL schema it reads is implicit rather than specified.

What does token-optimizer actually do?

Four layers, plus the dashboard:

AST structure maps — a 180K-token file becomes roughly 250 tokens of structure, 95–99% compression on the payload that hurts most.
Smart compaction with progressive checkpoints, condensing session state as it grows.
A 7-signal quality score, watching for mid-session context degradation. Nothing else in this category models that.
The HTML dashboard, reporting per-turn costs, cache analysis, model mix, subagent breakdown and drift.

It runs on Claude Code, OpenCode, OpenClaw and Codex. Its licence is PolyForm Noncommercial: free for personal and small-team use, paid licence for commercial use. Setup is heavier away from Claude Code and it carries a substantial local Python dependency.

What does each dashboard see?

token-optimizer sees inside the session; ccusage sees across your tooling. The quality score is the clearest example of the first. Every other tool in this category optimises cost and lets you discover the quality cost yourself, usually after a bad answer. A degradation signal alongside a cost signal is a real contribution, and no independent meter can produce it because it requires being inside the loop. ccusage's advantage is the opposite. It covers 15 agent sources, so if you use Claude Code for one project and Codex for another, it gives you one total. It also gives you something no vendor dashboard will: your own baseline variance, from weeks where you changed nothing. Knowing that your spend swings 20% on its own tells you how large an effect has to be before it counts as a result — and that number is what makes any other comparison meaningful.

Do you still need ccusage if you have the dashboard?

Yes, for three specific reasons, and none of them is distrust.

Scope. token-optimizer reports on the platforms it runs on. If your work spans agents it does not support, its dashboard is a partial view of your bill.
Baseline. You need spend data from before you installed it, and from weeks where nothing changed. Only an independent meter that was already running gives you that.
Licence-independence. If you eventually stop using token-optimizer — for licence reasons or any other — you lose the reporting with it. ccusage keeps running.

Install ccusage first, collect a few weeks, then install token-optimizer. That ordering costs nothing and it is the difference between a measurement and an impression.

What can neither of them tell you?

Whether a saving on one channel reached your invoice. Both report; neither runs the counterfactual. "What would this week have cost without the structure maps" is not a question either tool answers, and the only honest way to get at it is to change one thing at a time and compare weeks against your known variance.

Which one should you pick?

Install ccusage regardless. Free, zero-install, read-only, agent-agnostic. There is no scenario where the independent number leaves you worse off. Install token-optimizer if you are an individual or small team on Claude Code and large files dominate your reads — and after you have resolved the licence question, which is the only irreversible decision on this page. Do not treat the dashboard as a substitute for the meter. Different scopes, different independence, two minutes to have both.

How to apply this today

Run npx ccusage@latest before installing anything else. Four normal weeks gives you a variance baseline nothing else can provide retroactively.
Settle the licence question if this is commercial work.
Then install token-optimizer and change nothing else that week.
Read the quality score alongside the cost. It is the number the independent meter cannot give you, and the one most likely to change your mind.

What goes wrong (anti-patterns)

Rolling out a noncommercial-licensed tool across a company. Nothing to do with tokens, and the most expensive mistake available here. Installing the optimizer before the meter. You then have no before, and no way to construct one. Reading a vendor dashboard as an independent result. It is a good-faith report from inside the loop. Treating ccusage as an optimizer. It saves nothing. Its entire value is what you do with the number.

See also: