Caveman for Claude Code: The Real Savings Are Not in the Grunting

Caveman began in April 2026 as a joke: a prompt that told a coding agent to answer like a caveman. Short fragments, no greeting, no recap. It reached number one on Hacker News with 904 points, ThePrimeagen's verdict on video was "No way this actually works", and the repository has since passed 111,000 stars and 6,400 forks.

The joke kept its voice and outgrew its premise. Version 4.0.0, released on 13 October 2026, reorganises the project into six parts the README calls "rocks", and only one of them is the caveman voice. The rest are a local proxy that compresses what your agent reads, a router that picks the model and reasoning effort per request, a library of reusable scripts, and smaller tools for finding where tokens go.

That explains the GitHub language label, which says Go. Most of the code is now the compression engine and proxy behind those input-side rocks, with JavaScript and TypeScript for the CLI and installers and Python for the evaluation harness. The skill that made it famous is still a markdown file.

The whole repository is Apache-2.0. "Caveman" and the rock logo are trademarks of the author, Julius Brussee.

The most interesting file in the repo is not the skill. It is a page titled Honest Numbers, which measures the project's most famous claim and publishes the result even where it is unflattering. This article follows that thread, because it is the clearest guide to which parts of Caveman are worth installing.

The full install is one command:

npx @caveman-ai/cli@latest

It finds the agents and logins on your machine, shows what it is about to change, and waits for you to press Enter. It needs Node.js 22.13 or newer. Afterwards, plain claude runs through Caveman, as do Codex, Gemini CLI, OpenCode and, per the install matrix, more than 30 other agents. It runs locally, with your own API keys or your Claude Pro or Max login.

All six are on after install. Each has its own switch, caveman off browse for example, and caveman status shows what is running. Only Auto needs an account, and the account is free.

If you only want the voice, the skill installs on its own, with no proxy and no CLI:

npx skills add JuliusBrussee/caveman -g

Type /caveman ($caveman in Codex) if it does not start by itself, and say "stop caveman" to go back. Claude Code also has a plugin marketplace package, and Gemini CLI an extension.

This is the example the project is famous for. A normal agent explains a React re-render like this:

The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object.

Caveman mode says:

New object ref each render, so React re-renders. Wrap the prop in useMemo.

Same fix, 63 tokens down to 20. The README insists this is "a voice, not broken grammar", and the rules underneath are more careful than the meme suggests:

• Answer first. [thing] [action] [reason]. [next step]. No greeting, no "let me", no recap.
• One idea per sentence. The rules borrow from ASD-STE100, the Simplified Technical English written for aircraft maintenance manuals: 20 words at most, active voice, one term per thing.
• Meaning is never dropped. Articles can go. Not, never, no and only never go, and numbers and units stay exact.
• Payload stays verbatim. Code, commands, paths and error messages are left character for character.
• No theatre. No "me think", no chatter between tool calls, and if caveman phrasing is not actually shorter, plain English wins.
• It knows when to stop. Security warnings, irreversible actions and confused users get full sentences, then the grunting resumes.
• Your prompts stay yours. Caveman never rewrites what you type.

The negation rule is the one that makes terse output safe. Compress "do not run this against production" carelessly and you get "run against production". The rules protect those words explicitly.

There are three intensities. /caveman gives the 20-token answer above, /ultracave drops to 14 ("Inline object prop, new ref, re-render. useMemo."), and /megacave answers in Classical Chinese for 13 tokens, which is the most compressed and least readable of the three.

Here is the table the repo publishes for ten developer questions on claude-opus-5-5:

Read the first two rows before the last two. A plain two-word instruction takes the total from 6,983 to 4,334, about 38%, and the repo itself calls "be concise" the real baseline because current models already know how to do it. On top of that baseline, /caveman cuts 3% more at the median. /ultracave cuts 35% more, which is the variant that measurably goes further, at a real cost in readability.

The caveats are printed next to the numbers: ten questions, a single run, output length only, measured on the 3.1.0 rules and not yet re-run since. The rules themselves cost about 1,160 tokens of input.

The GitHub tagline still says the project "cuts 65% of tokens". The Honest Numbers page notes that earlier releases of the stats command applied a fixed 65% output ratio with no committed, reviewed result behind it. Current reports ignore those historical estimates, and the statusline no longer displays a savings figure at all.

It is unusual for a project at this scale to walk back its own headline number in its own documentation. It is also the most useful thing in the repo, because it tells you exactly where not to expect savings.

The deeper reason the voice matters less than it looks comes from the outside A/B tests the repo collects:

• One contributor analysed 662 real Claude Code sessions and found output was 0.3% of all tokens. Caveman's net effect on the bill was within ±0.2%.
• LemonCrow ran 300 runs per arm on claude-opus-4-8. Billed output fell 44.1%, yet total cost rose 0.06%. The rules added 1,532 tokens of cached context to every run.
• JetBrains ran 86 real coding tasks as a paired A/B: 8.5% fewer output tokens, with no measurable quality loss (p = 0.82).

Think about what a coding agent sends on each turn: the system prompt, the tool definitions, the conversation so far, every file it read and every tool result it got back. The reply is a sliver at the end of all that. Halving the sliver halves almost nothing. The repo's own summary is that output shrinks, but an agent run's bill is mostly input and cache re-reads, which an output-style rule cannot touch.

The voice does win where the reply is the bulk of the work. Adobe Research's CAVEWOMAN paper, which cites the repo, measured caveman-style output cutting cost 1.4 to 2.4 times per model across eight models and five datasets, and Elastic's remake for Elasticsearch MCP scenarios measured 63.6% fewer response tokens. Those are chat-shaped workloads.

Adobe also found the effect reverses on the other side of the conversation. Cavemanning your prompt makes answers worse, which is why Caveman never touches what you type.

The repo lists the cases where it loses outright:

• Terse coding Q&A. The fixed rule overhead can exceed any output saving, and one user measured a net loss.
• Per-request billing. GitHub Copilot charges premium requests, so a shorter answer is the same request and saves nothing. The same applies to any per-message pricing.
• Tool-side accounting. One Cursor A/B showed 4.3 million tokens with Caveman against 1 million without, at twice the wall-clock time. It was not reproducible, but the repo keeps it listed, because rule re-injection, retries and cache accounting can swamp output savings.

What is still missing is a published quality claim. A fidelity eval exists, with fixed cases and regex checks that numbers, negations and safety wording survived compression, but no reviewed snapshot is committed. If you run your own A/B, borrow the idea: a few patterns asserting that a "not" or a version number made it through, drafted against real replies in a regex tester, catch the failure a token count never will.

If output is the sliver, input is the bill, and 4.0 puts its weight there. The proxy compresses tool output before the model sees it. The README's benchmark ran Claude Code on six large files, each hiding one record the agent had to find:

Caveman got 18 of 18 answers right. Headroom, another compression wrapper run on the same suite, got 15 of 18 at 6.7% fewer tokens.

The gap between the file column and the session column is the lesson in miniature. A supported file shrinks by about 98%, but every request still carries the system prompt, tool definitions, conversation and the Caveman skill itself, so the session moves by a third. HTML went backwards because there is no HTML compressor yet, while the skill overhead was still counted. The repo kept that red row rather than dropping it.

The compression is lossy and query-aware: the engine keeps what looks relevant to the question. Every original stays on your disk, and the agent can pull it back from a local recovery store when the compressed view is missing something. Those recovery calls were counted in the benchmark.

Read the limits before you quote 33.2%. The fixtures are deterministic 60 to 95 KB files, each burying one record in noise, which is the ideal case for a needle-finding compressor. The session run dates from August 2026 on an older engine. And the raw harness artefacts are not in the public repo, so the result cannot be reproduced from a checkout, and the repo says to treat it as a pinned report.

You can get a lossless slice of this by hand, so we measured how big. Using the same o200k tokeniser Caveman reports in, we encoded two payloads three ways:

Minifying cut 38% and 43%. The common advice to convert JSON to YAML before pasting it into a prompt beats indented JSON, but it lost to minified JSON on both shapes, because YAML keeps every key name and spends tokens on indentation instead of braces. If you paste structured data into an agent by hand, a JSON minifier is the cheapest lossless win available. Reach for a JSON to YAML converter when a human has to read the prompt, not when the bill is the point.

Auto adds a model to your agent's picker. Choose it, and Caveman picks the model and reasoning effort for each request: a big model for a hard ask, a cheaper setting for an easy one.

That is 85 real coding tasks from SWE-Interact and SWE-Together, one attempt each, at 0.46 times the cost and under half the time.

The benchmark document is more revealing than the headline, because it shows what Auto actually did. On the Claude-only pool it sent 87% of requests to Opus 5.5 at medium effort, 8% to Opus at high, and 5% to Sonnet 5.5. The saving comes mostly from lower effort, not from switching to a cheaper model, and the document says so itself: against an agent already running Opus at medium effort, expect much less, and that case has not been measured.

The other caveats are stated just as plainly. The run is interim, 85 of 169 tasks. The quality interval is about ±7 points, so the arms cannot be told apart, and on SWE-Interact alone Auto is 6 points behind. Costs are list prices from the router's catalogue, not billed amounts, and the raw trajectories are not in the repo.

The practical reading: if you run xhigh effort by habit, the first cheap experiment is lowering effort yourself. Auto is the version of that experiment that decides per request.

caveman login                  # free account; Auto appears in the model picker
caveman providers add openai   # optional: more models, on your own key

It works in Claude Code, OpenCode and Codex. Any other model you pick runs exactly as picked, and without signing in there is no Auto and nothing is sent.

Code mode is the pattern of an agent writing a small script instead of making tool call after tool call, an approach both Cloudflare and Anthropic have written up. Its weakness is that the agent writes the same script every session and throws it away. On one machine, in one week, agents wrote the same script 394 times, and a Purdue study measured the habit at up to 9.57% of task cost.

Blocks keeps those scripts in your repository, checks them on every pull request, and hands them back. Eight ship with Caveman: json-peek, jsonl-stats, test-summary, first-error, wait-for, grep-defs, http-json and replace-in-file. When the agent starts typing a script a block already covers, it gets a one-line hint to use the block. It never denies or rewrites a command.

The third row is a loss: the block reads back more than a bare grep, and the row stays in the README anyway. That consistency, publishing the rows that lose, runs through the whole project.

caveman-blocks scan shows what your agents retyped this month without the script text leaving your machine, and caveman-blocks init writes the rules and the block index into your repo's AGENTS.md. Blocks is a pre-release (v0.1.0-rc.5), Python only, with no sandbox yet.

The rest of the toolkit is a set of narrower tools, most with their own numbers:

• `/caveman-compress <file>` shrinks memory files such as CLAUDE.md and keeps a backup. Across five test files it took 6,198 tokens down to 4,138, between 22.8% and 49.1% per file, with every heading, code block and path intact. Since a memory file is sent with every request, this saving compounds in a way a shorter reply does not.
• `caveman browse <url>` hands the agent a compressed web page: 121 tokens instead of 15,704 for a Playwright snapshot of a 200-row table. Tiny forms come out 2.3 times worse, and the README says so.
• Warm cache keeps Anthropic's prompt cache warm while you step away, but only when your own history says you usually come back in time, so the next request does not pay full price. Every warm is listed in caveman stats. Not measured yet.
• `caveman learn` ranks where your tokens go using agent history already on disk, and caveman learn implement applies fixes one diff at a time, only when you say yes.
• Middleware brings the same compression to Vercel AI SDK, LangChain, OpenAI and Anthropic SDK calls in your own code.

Inside the agent there are a few commands worth knowing. /caveman-commit writes a one-line Conventional Commit. /caveman-review returns one finding per line, in the form L42: 🔴 null deref. Guard it. cavecrew runs subagents that find, edit and review code and report back in caveman.

The most useful command, given everything above, is caveman trial -- claude, which A/B tests a real session on your own work. Every number on this page is someone else's workload. That one is yours.

The privacy section is specific, and it differs sharply by component:

• The skill runs on your machine and sends nothing. The exception is /caveman-compress, which sends the file you compress to your configured model provider.
• The CLI sends usage stats by default: commands run, token counts, Blocks usage counts, a random install ID, your OS and your IP address. Never your prompts, code, file paths or scripts. caveman telemetry off or DO_NOT_TRACK=1 turns it off for good.
• Auto, once you sign in and pick it, sends Caveman Cloud your latest ask with whatever the agent attaches to it, such as CLAUDE.md, memory or @-mentioned files, plus the ask before it, the end of the agent's last reply, tool names, effort and token counts. On the free plan, Caveman may keep that data to improve routing. caveman off routing stops it.
• Requests routed to a Caveman Cloud model pass through Caveman Cloud whole: system prompt, tool results and code. caveman providers cloud off stops that.

Two things follow. Telemetry that includes your IP address is on by default in the CLI, which is worth knowing before you install it on a work machine. And Auto, the rock with the biggest headline saving, is also the one that sends your context off the machine.

The commercial side of the project is Caveman Cloud, aimed at teams building their own agents rather than using one: run tracing, evals on real traffic, and an "autopilot" that proposes cheaper changes, tests them on recorded work, and ships only when the evals hold, with you approving the pull request. The open-source CLI and skill do not require it.

It depends on which rock you came for, and the repo's own numbers make the answer unusually clear.

For the voice alone, install just the skill, but first add "Answer concisely." to your CLAUDE.md and compare. The repo's own table says that gets you most of the way, and /caveman adds about 3% on top. If you want a real further cut, /ultracave is the variant with the 35% number behind it.

If your sessions read big logs, CSVs or test output, the Read less proxy is the rock with the strongest evidence: 33.2% fewer input tokens at held accuracy on its benchmark, with the limits stated above.

If you run Opus at xhigh effort by default, Auto's saving is mostly an effort saving. Try lowering effort yourself, or let Auto decide per request, knowing it sends context to Caveman Cloud.

If you pay per request, as with GitHub Copilot, skip the voice. A shorter answer is the same request.

Whichever you pick, measure it. Run caveman trial, or compare provider-billed totals on the same task with and without Caveman, and turn it off for any workload where the bill goes up. That instruction comes from the repo itself.

Caveman became famous as a joke about grunting. What makes it worth trusting is the page that measured the grunting and reported, plainly, that it was not where the money was.