caveman vs ccusage: the only pair you can settle in a week

Part of the reduce Claude Code token usage pillar. This is the one comparison in the category that a single number resolves completely.

Is caveman or ccusage what I need?

ccusage first, always — because it produces the one number that tells you whether caveman is worth installing at all. caveman reduces the tokens your model emits, by an average of 65%. ccusage tells you what fraction of your spend those emitted tokens represent. For most agent coding work, that fraction is small. Inbound traffic — file contents, command output, tool manifests, replayed conversation — typically dominates outbound by around an order of magnitude. Cut 65% off a tenth of your bill and you moved the total by a few points, which is real and is not what the headline suggests. But the fraction is not the same for everyone, and that is the entire point of measuring it rather than assuming it. I maintain an open long-session benchmark and sell a competing tool; on that benchmark caveman shows no measurable session-cost saving, which is exactly what the arithmetic above predicts for agent workloads.

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, 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 window, so you see where you stand inside it rather than after it. It is read-only and reduces nothing, and it offers no counterfactual — observed spend only, never "what I would have spent without tool X". The JSONL schema it reads is implicit rather than specified.

What does caveman actually do?

It switches the model into telegraphic speech. A JavaScript skill or plugin for 30-plus agents with four levels — lite, full, ultra, wenyan — triggered by /caveman. Auto-detection covers Claude Code, Codex, Gemini, Cursor, Windsurf, Cline and Copilot, and install is a 30-second curl or irm. Its benchmark deserves respect: average 65% output reduction, range 22–87%, measured on raw Claude API receipts against an already-concise baseline. Not a simulation, not an estimate. It also ships two input-side tools that most write-ups miss entirely:

caveman-shrink, an MCP middleware that wraps any MCP server and compresses its tool descriptions — a standing per-turn cost almost nothing else touches.
caveman-compress, which rewrites CLAUDE.md and memory files into telegraphic form, around 46% input savings on a file re-sent every turn.

The honest cost is in its own readme: style enforcement can degrade reasoning quality on nuanced explanations.

How do you settle this in a week?

Read one ratio and act on it.

Run npx ccusage@latest. Seconds, nothing installed, reads transcripts you already have.
Find your input and output token totals for a normal week.
Divide. If output is under 10% of your traffic, caveman's speaking style cannot move your bill more than a rounding error, no matter how well it works.
Then decide separately about caveman-shrink and caveman-compress, because those are input-side and the ratio above does not apply to them at all.

That last step is the one people skip. The style is what caveman is famous for and it is the part your ratio may rule out; the MCP middleware and the memory-file rewriter are quietly the more broadly useful half of the project.

When does the answer flip?

When your usage is chat-shaped rather than agent-shaped. Long generated explanations, documentation drafts, code written from scratch rather than edited, and comparatively little file reading. There the output side is a real share of the bill, output tokens are billed at a higher rate per token, and caveman's 65% becomes a number worth having. Which shape you are in is not obvious from the outside, and it changes by project. Measure it rather than assuming; that is what the ratio is for.

What can neither of them tell you?

Why your inbound tokens are what they are. ccusage reports totals, not causes: it will not tell you that eleven of your last twenty tool calls re-read the same four files, or that a connected MCP server you never call is charging you on every turn. caveman does not look at inbound traffic at all beyond its two side tools. For that you need something on the tool boundary that reports per-channel, or a session you watch by hand.

What does the meter show that the ratio alone hides?

Cache tokens, and the per-model split. Both live in ccusage and neither shows up in caveman's savings badge. Cache tokens matter because cached input is billed at a fraction of fresh input on every major provider. A high hit rate is the largest single asset a long session has, and anything that quietly lowers it costs more than a raw token count suggests. caveman's speaking style does not touch the prompt prefix, so it is safe on that axis — but caveman-compress rewrites your memory file, which is part of the prefix. Rewrite it once and the saving is permanent; rewrite it every week and you invalidate the cache each time. The per-model split matters because routing is usually cheaper than optimising. If one model is draining far faster than the others, sending the cheap work to the cheap model costs nothing to implement and is invisible without a breakdown. And the meter gives you something no benchmark can: your own week-to-week variance. Two ordinary weeks rarely cost the same, and knowing how much your spend moves on its own tells you how large an effect has to be before you can honestly claim to have seen it.

Which one should you pick?

Install ccusage regardless. Free, zero-install, read-only, and it is the instrument this entire page depends on. Install caveman if your ratio says output matters, or specifically for caveman-shrink if you run MCP servers. Start at lite and read the output before going further. Skip the caveman style if you are doing agent coding work and your ratio confirms the usual 10-to-1 asymmetry. It is not a bad tool; it is a tool aimed at the smaller half of your bill.

How to apply this today

Get the input/output ratio before installing anything. It is one command and it settles the comparison.
Treat caveman-shrink as a separate decision from the speaking style. Different side of the pipe, different arithmetic.
If you enable the style, read a few answers at lite first and judge the reasoning quality yourself.
Re-measure after a week, not after a task.

What goes wrong (anti-patterns)

Installing caveman on an agent workload because 65% sounds large. It is large, on the smaller channel. Using ultra on work you need to understand. The readme warns about degraded nuanced reasoning. Believe it before you debug a wrong answer. Skipping caveman-shrink because you rejected the style. They are independent, and the middleware is the one with no quality trade-off. Treating ccusage as an optimizer. It saves nothing. All of its value is in what you do with the number.

See also: