caveman vs tokensave: speech or structure?

Part of the reduce Claude Code token usage pillar. This page is the head-to-head between the two lightest-weight installs here.

Is caveman or tokensave the better choice?

tokensave, for agent coding work — because it is on the inbound side and inbound is where the tokens are. caveman compresses the model's speech. tokensave gives the agent a symbol index so it stops opening files to find things. Inbound traffic typically dominates outbound by around an order of magnitude in agentic work, so the two are not playing for the same stakes. That said, caveman ships one component that lands squarely on tokensave's own overhead, and it is the most interesting thing on this page. More on that below. I maintain an open long-session benchmark and sell a competing tool. caveman shows no measurable session-cost saving there; tokensave has not been measured and publishes no benchmark of its own.

What does tokensave actually do?

It builds a symbol index and serves it over MCP. A Rust server with a semantic knowledge graph in libSQL with FTS5, built by tree-sitter extraction across 34 languages, exposing 48 MCP tools. What sets it apart:

Compiled. Fast startup, low memory, no runtime to install. Homebrew on macOS, Scoop on Windows, prebuilt binaries elsewhere.
Multi-branch indexing. Diff and search across branches without switching checkout — nothing else in this category does that, and it removes a class of context-burning git checkout round-trips.
Subprocess isolation. One parser crashing on a malformed file does not take the service down, which matters with 34 grammars in play.
Atomic edit primitives with AST rewriting. The agent renames a symbol through the tree rather than through a regex, avoiding the shell-quoting and partial-match hazards that make agentic edits fail quietly.

Its gaps: no output filtering, so command output arrives at full size; navigation only, with no semantic vector search and no structural compression; framework detection limited to fourteen hardcoded frameworks; and no published savings numbers.

What does caveman actually do?

It switches the model into telegraphic speech. A JavaScript skill or plugin for 30-plus agents at four levels — lite, full, ultra, wenyan — triggered by /caveman. Auto-detection across Claude Code, Codex, Gemini, Cursor, Windsurf, Cline and Copilot; a 30-second curl or irm install; a statusline badge showing lifetime savings. Its benchmark is honest in a way this category rarely is: average 65% output reduction, range 22–87%, measured on raw Claude API receipts against an already-concise baseline. And it ships two input-side tools:

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

The stated cost: style enforcement can degrade reasoning quality on nuanced explanations.

Where do they actually touch?

caveman-shrink can wrap tokensave, and tokensave is the tool in this category that most needs it. tokensave exposes 48 MCP tools. Their definitions are sent as input tokens ahead of your first message, on every turn, whether or not the agent queries the index once. That is the largest standing manifest cost of any tool in this comparison set, and tokensave's own reporting says nothing about it. caveman-shrink exists precisely to compress those descriptions. So the pairing is not "output tool plus input tool" — it is one tool paying down part of the other's fixed cost. If you run tokensave, caveman-shrink is worth installing even if you never enable the caveman speaking style at all. That is the concrete, checkable reason to read past the headline on both projects.

Which side of the bill are you on?

Measure it; do not assume it. One week with npx ccusage@latest gives you an input/output ratio, and that ratio decides most of this page:

Input dominates by 10x — the usual case for agent coding. tokensave is on the right side; caveman's style is a rounding error, though caveman-shrink still applies.
Output is a real share — chat-shaped work, long generated explanations, code written from scratch. caveman's 65% becomes a number worth having, and output is billed at a higher rate per token.

Neither tool tells you which case you are in. That is why the meter comes first.

What does neither of them do?

Command output at the tool boundary. tokensave never sees it; caveman governs model speech, not tool results.
Whole-file reads for editing. An index says which file; nothing here shrinks the file the agent then opens.
Re-reads. Same file, four times, four charges. An index lowers the odds; neither deduplicates.
Conversation history. Neither compresses the window, which on a long session is the largest single accumulation.

Which one should you pick?

Pick tokensave if you work across many languages, review branches often, or want the safer edit path AST rewriting gives you. It is also the one of the two that changes what the agent reads rather than what it says. Pick caveman if your work is output-heavy, or specifically for caveman-shrink — which is worth having regardless, and doubly so alongside a 48-tool MCP server. Pick both if you run tokensave and want its manifest cost brought down. That combination is the strongest argument on this page.

How to apply this today

Get your input/output ratio first. One command, and it settles the style question.
If you install tokensave, count tool calls before and after — that is the metric an index moves.
Install caveman-shrink alongside it. A 48-tool manifest is charged every turn and nothing in tokensave addresses that.
Disconnect the index on terminal-only sessions. You are paying the manifest for nothing.

What goes wrong (anti-patterns)

Installing caveman's style on an agent workload because 65% sounds large. Large percentage, small channel. Leaving a 48-tool manifest connected out of habit. It is billed on every turn including the ones that never query it. Treating "not benchmarked" as "does not work". tokensave publishes no figure; that is missing evidence, not evidence of failure. Running ultra on work you need to understand. The readme warns about degraded nuanced reasoning.

See also: