Caveman Got to 85,000 Stars Shrinking What Your Agent Says. Now It Rewrites What Your Agent Reads.

The trending Claude Code skill that makes your agent talk like a caveman has an exception list for security warnings. That list covers replies. It doesn't cover the memory files and tool descriptions the skill now compresses too.

Buried in the middle of caveman's SKILL.md is a section called Auto-Clarity. It tells the model to stop compressing and write normally when it hits security warnings, irreversible action confirmations, multi-step sequences where dropping conjunctions could scramble the order, or any point where the compression itself creates ambiguity. The example it gives is "migrate table drop column backup first", four instructions with no way to tell what happens when.

That's a maintainer who understands his own tool's failure mode precisely. Compression is safe until word order carries a decision, and then it isn't.

Which raises the question the repo hasn't answered yet: that exception list governs what the agent says. Two of caveman's newer pieces compress what the agent reads, and nothing like Auto-Clarity guards those.

What the thing is, before the argument

Caveman is a system-prompt skill. Install it and your coding agent drops articles, filler, pleasantries, and hedging, answers in fragments, and keeps code, commands, and error strings byte-for-byte exact. "New object ref each render. Wrap in useMemo." Six levels, from lite through ultra to three flavors of classical Chinese. MIT licensed, no telemetry, works with Claude Code, Codex, Gemini, Cursor, and 30-plus other agents.

It is also, right now, one of the most-starred agent skills that has ever existed. Three weeks ago it was under a thousand stars. GitHub served me three different counts across three page loads in the same research session today: 78.8k, 83.8k, and 85.6k. I'd treat any single number as a snapshot rather than a fact, but the direction is not ambiguous.

The headline claim is 65% fewer output tokens, averaged across ten prompts with a range of 22% to 87%, measured against default verbose replies with real Claude API token counts. The benchmark harness is committed to the repo.

The most honest file in the repo, and what it doesn't cover

Before I criticize anything, credit where it's due. docs/HONEST-NUMBERS.md is better disclosure than most vendors ship. It says the skill costs about 1,000 to 1,500 input tokens per turn just to exist. It says session-level savings on output-heavy work land around 14% to 21%, not 65%, "and below zero on terse ones." It links the issues where users proved it: #145, where someone measured net-negative on short coding Q&A and the maintainer wrote "They were right"; #506, where Copilot bills per request so a shorter answer costs the same; and #550, a Cursor A/B showing 4.3M tokens with caveman versus 1M without and double the wall-clock time, which the maintainer couldn't reproduce and published anyway. It says the /caveman-stats savings line is an estimate and labels it est. in the output.

Now read the opening paragraph of that same file: "It makes the model write shorter output. That is the whole mechanism. It does not compress your input, your context, your files, or the model's thinking tokens."

Then read the fourth row of the table directly underneath it, which lists /caveman-compress on memory files at "~46% average input reduction, per session, for those files only."

Both statements are in the same document, about eight lines apart. The doc is honest; it's just describing a tool that outgrew its own summary while the summary stayed put.

Where the compression crossed over

Three pieces of caveman now touch the agent's inputs.

/caveman-compress <file> rewrites a memory file such as CLAUDE.md into caveman-speak. The README's receipts table shows real files going from 706 tokens to 285, 1,145 to 535, 1,122 to 636, averaging 46% smaller. The pitch, quoted directly: "Every session after, that file loads ~46% smaller. Input tokens saved forever, not just one reply."

caveman-shrink is MCP middleware. It wraps any MCP server and compresses its tool descriptions.

And on Claude Code, a hook writes a flag file each session so the agent speaks caveman from message one without anyone typing /caveman.

Take those three together and the tool has moved from a style toggle on the output side to a rewrite pass on the input side. Your standing instructions get shortened. Your tool descriptions get shortened. Neither of those is a reply you skim and move past. They're the text the model consults when it decides what to do.

Here's why that's a different risk class, and it's the same reason Auto-Clarity exists. If a compressed reply loses a qualifier, you're reading it and you notice. If a compressed CLAUDE.md loses "run the migration on staging first, never against prod," you don't notice, because you're not reading your memory file. You're reading the pull request it produced three days later.

An MCP tool description is worse still. That text is the entire basis on which the model picks one tool over another and fills in its arguments. Squeeze "deletes the record permanently and cannot be undone" into "delete rec, permanent" and you've saved maybe eight tokens off a description that gets read once per session and shapes every call after it.

The repo has a benchmark for output token counts. It has no benchmark for whether a compressed instruction file produces the same decisions as the original. That's not an accusation of sloppiness, it's a hard thing to measure. But it means the 65% number and the 46% number are load-bearing in completely different ways, and only one of them has been tested for what it actually costs.

Put this into practice

If you want caveman, and there's a real case for it, here's the low-friction version.

Install for one agent, not all of them. The headline install is curl | bash and it finds every agent on your machine and writes to each one. The INSTALL.md matrix has per-agent paths. claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman touches one thing you can point at.

Run the A/B the repo tells you to run. Same task, twice, with and without, then compare your provider's own usage page. HONEST-NUMBERS says this outranks anything the repo prints, and it's right. Their rule of thumb: replies over about 1,500 to 2,000 output tokens and you probably save money, under that and you probably don't.

Leave /caveman-compress off your CLAUDE.md until you've read the diff. If you do run it, commit the file first, run the command, then read the diff line by line the way you'd read a PR. You're looking for one thing: did any conditional, ordering word, or "never" survive as something weaker.

Skip caveman-shrink on any MCP server with write access. Read-only lookup servers, sure. Anything that can edit a file, hit an API with side effects, or spend money, leave the descriptions alone. The token savings there are rounding-error small and the failure is a wrong tool call.

Use lite if you're unsure. It drops filler and hedging but keeps articles and full sentences. Most of the readability win, much less of the ambiguity risk.

The honest limitations

Caveman is not a bad project and this is not a takedown.

The brevity effect it cites is real research, not marketing: the README points to a March 2026 paper, Brevity Constraints Reverse Performance Hierarchies in Language Models, which the repo says tested 31 models and found constraining large models to brief answers improved accuracy by around 26 points on some benchmarks. Attribute that to the paper, not to caveman, and go read it yourself if it matters to your decision.

The metadata does drift. The SKILL.md description claims "~75%" while the README benchmark says 65%, which is the kind of stale line every fast-growing repo carries. And there's a commercial motive now sitting behind the honesty: the README ends with a waitlist for "Caveman 2," which exists to make the savings numbers provable across a team, meaning the current numbers are being sold as the problem the paid thing solves.

The risks I've described are structural, not malicious. No telemetry, no backend, no network calls after install; the security posture is clean. The failure mode isn't someone doing something bad to you, it's a token optimizer editing text whose value was never measured in tokens.

What to do with this

Compression is going to keep spreading through agent stacks, because token bills are real and the wins on chatty output are genuine. The question that decides whether it helps you is which text you point it at.

Output is safe to compress because you read it. Standing instructions and tool descriptions are the agent's decision inputs, and nobody reads those after the day they're written. That's precisely why compressing them feels free, and precisely why it isn't.

Open your own CLAUDE.md right now and find the sentence that would cause the most damage if it got 46% shorter. Every stack has one. Once you know which sentence it is, you'll know exactly how much of this tool you want.

Sources: JuliusBrussee/caveman README, caveman SKILL.md, caveman docs/HONEST-NUMBERS.md, Brevity Constraints Reverse Performance Hierarchies in Language Models (arXiv 2604.00025).