rtk vs ccusage: two counters that disagree

Part of the reduce Claude Code token usage pillar. This page is the head-to-head between a tool that saves and reports, and a tool that only reports.

Is rtk or ccusage what I need?

They answer different questions, and running both is how you learn something neither one tells you alone. rtk filters shell command output and reports what it saved doing so. ccusage reads your agent's transcripts and reports what you actually spent. The first is a per-channel counter, the second is the bill. The interesting case is when they disagree — and they usually do. rtk gain can show a large cumulative saving while your ccusage total barely moves. That is not a bug in either tool. It is the single most instructive measurement available in this whole category, and most people never make it because they only install one of the two. I maintain an open long-session benchmark and sell a competing tool. On that benchmark rtk lands at roughly break-even. Read the mechanism below rather than the placing.

What does rtk actually do?

It filters command output at the shell boundary. A Rust CLI proxy with over a hundred command-specific filters — git, cargo, npm, pytest, docker, aws — and a transparent hook, so you keep typing commands exactly as before while rtk compacts what comes back. One binary, under 10 ms of startup, no token cost for the integration itself. There is a TOML DSL for adding your own filter rules, and rtk gain reports savings per command from a SQLite store. The reductions on noisy tools are large and easy to see: around 90% on cargo test, around 80% on git operations. Its structural limits are precise. The hook only covers bash, so the agent's built-in Read, Grep and Glob go around it entirely — and on most agents those carry the bulk of the tokens. No retrieval, no structural compression of source files, no deferral of MCP manifests, and no native Windows PowerShell support.

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. For Claude Pro and Max subscribers the standout is the 5-hour billing block view, matching Anthropic's rolling limit window, so you see where you are inside it rather than after it. It is read-only and reduces nothing, and it has no counterfactual — it reports observed spend, never "what you would have spent without tool X". The JSONL schema it reads is implicit rather than specified.

Why do the two numbers disagree?

Because rtk gain measures its own denominator and ccusage measures yours. rtk gain answers: of the bytes that passed through rtk's filters, how many did it remove? That is a real number and it is honestly computed. But the denominator is shell command output that rtk intercepted, not your session. If shell output is a fifth of your traffic, a 70% cut there is a 14% cut overall — and if the agent does most of its reading through built-in tools rtk never sees, the share is smaller still. ccusage answers: what did the provider charge? That number includes everything rtk cannot see — file reads through the agent's own tools, MCP manifests sent before your first message, the conversation window replayed on every turn, and cache misses. So the two do not contradict each other. They have different scopes, and the ratio between them tells you what fraction of your bill rtk was ever in a position to touch. That fraction is the number worth knowing, and it is specific to how you work.

What the gap tells you

Run both for a week and the arithmetic points somewhere useful:

rtk gain large, ccusage flat. Your spend is not in shell output. Look at file reads and tool manifests next; rtk is working correctly on a channel that is not yours.
rtk gain small. You do not run enough noisy commands for a filter to matter. Nothing to fix, and nothing to gain by tuning it.
Both moved. Terminal-heavy work, and rtk is the right tool for you. Keep it.
ccusage up while rtk gain grows. Something else changed that week. This is why changing one thing at a time matters more than any tool choice on this page.

What can neither of them tell you?

Why the tokens were spent. ccusage reports that a session cost more than usual; it will not tell you that eleven of your last twenty tool calls re-read the same four files. rtk gain reports what it filtered; it says nothing about what it never saw. Between them they cover "how much" on two scopes and neither covers "what caused it". For that you need to watch a session, or put something between the agent and its tools that reports per-channel.

Which one should you pick?

Install ccusage regardless. Free, zero-install, read-only, and it is the instrument every other decision depends on. Install rtk if your day is builds, tests, containers and infrastructure commands, and you are on Linux or macOS. The saving is real on that channel and rtk gain lets you size it yourself within a week. Install both if you want to know what fraction of your bill the shell actually represents. That single ratio decides more of your optimisation strategy than any feature comparison will.

How to apply this today

Run npx ccusage@latest first and write down a week of totals before installing anything that changes behaviour.
Install rtk, then compare rtk gain against the ccusage total, not against itself. The ratio is the finding.
Change one thing at a time. Two changes in a week produce one uninterpretable result.
If the gap is large, go looking at file reads and MCP manifests. That is where the rest of the bill lives.

What goes wrong (anti-patterns)

Reading rtk gain as a bill reduction. It is a per-channel figure with its own denominator, honestly computed and easy to misread. Installing an optimizer with no meter. You end up with an opinion rather than a result. Expecting rtk to cover the agent's built-in file tools. The hook is on bash by design. Treating ccusage as an optimizer. It saves nothing. All of its value is in what you do with the number.

See also: