codegraph vs caveman: index the repo or shorten the answers?

Part of the reduce Claude Code token usage pillar. This page is the head-to-head, and the interesting part is a place where they overlap that neither README advertises.

Is codegraph or caveman the better token optimizer?

codegraph, if you only install one — because agent traffic is overwhelmingly inbound and codegraph is on the inbound side. codegraph indexes your code so the agent stops opening files to find things. caveman changes the model's output style so it emits fewer tokens saying the same thing. Both publish real numbers on their own channel. Neither shows a measurable session-cost saving on my open long-session benchmark — I run it and I sell a competing tool, so read the mechanism, not the placing.

What does codegraph actually do?

It replaces file-hunting with a query. tree-sitter parses your source into an FTS5 SQLite knowledge graph served over MCP: impact analysis, call graphs, symbol lookup, across 20-plus languages and 14 frameworks. Instead of opening four files to find where a function is used, the agent asks the index. It is the lowest-friction install in the category. A bundled Node.js runtime means no version management, and an interactive installer detects eight agents — Claude Code, Cursor, Codex, opencode, Hermes, Gemini, Antigravity, Kiro — and writes their MCP configuration itself. The file watcher is debounced and shows a staleness banner when files are pending re-index, so the agent knows when its answer might be behind the working tree. Its published benchmark: −35% cost and −71% fewer tool calls, median over seven repositories. The tool-call half is the one to trust — it follows mechanically from having an index and you can verify it in one session. The cost half shows visible run-to-run variance, including a four-run spread on Tokio in codegraph's own reporting.

What does caveman actually do?

It makes the model talk in telegraph. A JavaScript skill or plugin for 30-plus agents that switches output to compressed "caveman talk" at four levels — lite, full, ultra, wenyan — triggered with /caveman. Its benchmark is unusually honest: an average 65% output reduction, range 22–87%, measured against raw Claude API receipts versus an already-concise baseline. Not a simulation, not a token estimate — receipts. It ships two things beyond the style, and they are the parts people skip past:

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.

Install is a 30-second curl or irm with auto-detection across Claude Code, Codex, Gemini, Cursor, Windsurf, Cline and Copilot. A statusline badge shows lifetime savings. The honest cost is in its own readme: style enforcement can degrade reasoning quality on nuanced explanations. On work where the explanation is the deliverable, that is a bad trade.

Where do they actually meet?

caveman-shrink can wrap codegraph. This is the one genuine interaction between them and it is almost never mentioned. codegraph is an MCP server, so its tool definitions are sent as input tokens before your first message, on every turn, whether or not the agent ever queries the index. That is a standing cost that codegraph itself does nothing about and that no benchmark of it reports. caveman-shrink exists precisely to compress those descriptions. So the pairing is not "input tool plus output tool". It is "input tool, output tool, and one of them pays part of the other's overhead". If you run codegraph and you run MCP servers generally, caveman-shrink is worth installing even if you never enable the caveman speaking style.

Why do the published numbers not add up to a session saving?

Because they have different denominators, and both denominators are smaller than the bill. −71% tool calls is a real, verifiable reduction in navigation. It is silent about command output, about the files the agent opens to edit, about re-reads, and about conversation history. 65% off output is real too, and output is the smaller side of agent traffic — typically by around an order of magnitude. A large percentage of a small number stays small. Add them and you still have not touched the two largest accumulations in a long session: everything that arrives at the tool boundary, and the window that grows across turns.

What does neither of them cover?

Command output at the tool boundary. cargo test, npm install, a stack trace: codegraph is not on that path and caveman only governs model speech, not tool results.
Whole-file reads for editing. An index tells the agent which file; it does not shrink the file it then opens.
Re-reads. The same file entering context four times in one session costs four times. An index lowers the odds; neither deduplicates.
Conversation history. Neither compresses the window that accumulates across a long session, which on multi-hour work is the largest single accumulation of all.

That list is why two tools with honest, verifiable numbers can both land at break-even over a session. Each is telling the truth about the slice it owns, and the slices do not add up to the bill.

Which one should you pick?

Pick codegraph if you install one thing. It is on the bigger side of the bill, it has the easiest install here, and its failure mode — a stale index — announces itself. Pick caveman if your agent generates a lot of prose, or specifically for caveman-shrink and caveman-compress. Those two are input-side wins most tools in this category do not offer at all. Use lite on work whose explanations you will actually read. Pick both if you want cheap coverage at two ends plus the manifest compression. They do not conflict and the install cost of each is minutes. Pick neither yet if you have not looked at your input/output split. One week with ccusage answers this page better than any feature table.

How to apply this today

Get your input/output ratio. If input dominates by 10x — it probably does — you have your answer about which side to work first.
Count tool calls before and after if you install codegraph. That is the metric it moves.
Install caveman-shrink if you run MCP servers, independently of the style. Tool descriptions are billed every turn and almost nothing else touches them.
Start caveman at lite and read the output before going further.

What goes wrong (anti-patterns)

Optimising output first. Visible, satisfying, and the smaller half on agent traffic. Running ultra on work you need to understand. The readme warns about degraded reasoning. Believe it before you debug a wrong answer. Ignoring the MCP manifest cost of your index. codegraph adds one and reports nothing about it. Reading a per-channel percentage as a session saving. −71% tool calls and −65% output are both true and neither is your invoice.

See also: