caveman vs token-optimizer: output style or structure maps?

Part of the reduce Claude Code token usage pillar. This page is the head-to-head between the strongest output-side tool and one of the strongest input-side ones.

Is caveman or token-optimizer the better choice?

token-optimizer for agent coding work — but read its licence before you install it anywhere commercial. caveman cuts the tokens the model emits, by an average of 65%. token-optimizer attacks the inbound side, most sharply by turning a 180K-token file into roughly 250 tokens of structure. In agentic sessions inbound traffic dominates outbound by around an order of magnitude, so the two are aimed at very different shares of the same bill. The licence is the other axis and it is not a footnote. caveman is free and openly licensed. token-optimizer is PolyForm Noncommercial: free for personal and small-team use, paid licence required for commercial use. I maintain an open long-session benchmark and sell a competing tool. caveman shows no measurable session-cost saving there; token-optimizer has not been measured on it.

What does token-optimizer actually do?

Four layers, aimed at genuinely different problems:

AST structure maps. A 180K-token file becomes roughly 250 tokens of structure — signatures, symbols, shape. That is 95–99% compression on the payload that hurts most, and it works because the agent usually needs to know what is in a file rather than to read it.
Smart compaction with progressive checkpoints. Session state is condensed as it grows instead of being dumped and restarted.
A 7-signal quality score, watching for the mid-session degradation where an agent's answers get worse because its window filled with noise. Almost nothing else in this category models that.
A full HTML dashboard: per-turn costs, model mix, cache analysis, subagent breakdown, drift detection.

It runs on Claude Code, OpenCode, OpenClaw and Codex. Setup is heavier away from Claude Code, it carries a substantial local Python dependency, and it exposes no transparent API for third-party integration.

What does caveman actually do?

It switches the model into telegraphic speech, at four levels — lite, full, ultra, wenyan — through a /caveman command. A JavaScript skill or plugin covering 30-plus agents with auto-detection, installed by a 30-second curl or irm, with a statusline badge showing lifetime savings. Its benchmark is the most honest in the category: 65% average output reduction, range 22–87%, measured on raw Claude API receipts against an already-concise baseline. Not a simulation, not a token estimate. Two input-side extras come with it:

caveman-shrink, an MCP middleware that compresses any server's tool descriptions.
caveman-compress, which rewrites CLAUDE.md into telegraphic form — around 46% input savings on a file re-sent every turn.

The stated trade-off: style enforcement can degrade reasoning quality on nuanced explanations.

Two honest benchmarks, two different questions

This is the pair where both vendors measured carefully and neither number answers the question you have. caveman measured output reduction against real API receipts. That is rigorous and it is scoped to the model's own words. token-optimizer measured compression on a file: 180K tokens to 250. Also rigorous, also scoped — to the payload it replaced, not to a session. Neither is measuring "what happens to my monthly bill", which depends on how much of your traffic falls in each scope. That is why the first useful action on this page is not installing either one, but running npx ccusage@latest and reading your input/output split.

Do they compose?

Yes, without friction. They operate on opposite sides of the model and share no state. Running both is coherent for anyone whose licence position allows token-optimizer. There is even a small synergy: token-optimizer's dashboard reports per-turn costs and cache analysis, so it gives you a way to see whether caveman's style is doing anything measurable on your workload. That is more feedback than either tool provides on its own.

What does neither of them do?

Command output at the tool boundary. token-optimizer's compaction is a session-level operation, not a per-command filter; caveman governs speech, not tool results.
MCP manifests. token-optimizer does not defer them. caveman's caveman-shrink compresses them, which helps but is not the same as not sending them.
Semantic retrieval. Neither replaces a search across the codebase with a targeted answer.
Re-reads. A structure map makes each read smaller; nothing here notices the repetition.

Which one should you pick?

Resolve the licence first if you work at a company. PolyForm Noncommercial means a paid licence for commercial use, and deciding that after a team rollout is the expensive order. Pick token-optimizer if you are an individual or small team on Claude Code and large files dominate your reads. The AST structure map is the strongest single mechanism here and the dashboard shows you whether it worked. Pick caveman if your work is output-heavy, or for caveman-shrink and caveman-compress regardless — both are input-side, both apply broadly, and neither carries the style's quality trade-off. Pick both if the licence allows and you want coverage on both sides.

How to apply this today

Settle the licence question first. Two minutes, and it is the only irreversible decision on this page.
Get your input/output ratio. It tells you whether caveman's style is worth enabling at all.
Run caveman-compress once on your memory file, then leave it. Permanent per-turn saving with no quality cost — and re-running it repeatedly just invalidates the cached prefix.
Find your largest file reads. If a handful of big files dominate, a structure map is the highest-leverage change available.

What goes wrong (anti-patterns)

Rolling out a noncommercial-licensed tool across a company. The most expensive mistake on this page, and it has nothing to do with tokens. Installing caveman's style on an agent workload because 65% sounds large. Large percentage, smaller channel. Reading 180K-to-250 as a session saving. It is compression on one payload, honestly measured, at a scope smaller than your bill. Enabling ultra on work you need to understand. The readme warns about degraded nuanced reasoning.

See also: