Caveman.MD: The Complete 2026 Guide to AI Agent Token Compression (65% Output Reduction)

In April 2026, JuliusBrussee/caveman shipped a deceptively simple idea: make Claude (and 30+ other AI agents) write like a caveman to cut output tokens by 65%. The tagline says it all — “why use many token when few do trick.”

Within weeks, the project found its way into AGENTS.md rulesets, Claude Code plugin marketplaces, Codex extensions, and Gemini CLI configurations across the AI coding community. If you’ve been wondering what “caveman.md” means when you see it referenced — or how it differs from CLAUDE.md / AGENTS.md / .cursorrules — this is the complete reference.

This article covers what Caveman is, the four compression levels, the benchmark data, installation across every supported agent, and where Caveman fits in the rule-file ecosystem we’ve documented in our AGENTS.md vs CLAUDE.md vs .cursor/rules guide.

What Caveman Actually Is

Caveman is not a new rule file format. It’s a set of instructions that gets dropped into your existing AGENTS.md (or CLAUDE.md, or .cursorrules) telling the model to compress its output. Same delivery mechanism as any other AGENTS.md content, but the content is specifically about eliminating filler.

From the official README: “Caveman only affects output tokens — thinking/reasoning tokens untouched. Caveman no make brain smaller. Caveman make mouth smaller.”

The result, measured across 10 representative tasks, is an average 65% reduction in output tokens (range: 22–87%). Code, URLs, file paths, and technical accuracy remain byte-perfect — only the natural-language prose surrounding the technical content gets compressed.

Why “Caveman”?

The naming reflects the style. Instead of:

“I’ll examine the file and analyze the structure to understand what we’re working with.”

You get:

Read file. Structure clear.

This isn’t a gimmick. A March 2026 research paper cited in the Caveman docs reports that “constraining large models to brief responses improved accuracy by 26 points on certain benchmarks.” Verbose output may correlate with worse reasoning, not better — by removing the apologetic preamble and meta-commentary, Caveman pushes the model toward direct, accurate answers.

The 4 Compression Levels

Caveman ships with four distinct compression modes:

You pick a level via /caveman <level> once per session, or set a default in your AGENTS.md. The model continues thinking at full fidelity — only the surface text changes.

The 10 Rules (Distilled)

The Caveman ruleset distils the compression philosophy into ten directives:

1. No filler phrases — drop “I’ll go ahead and…”, “Let me…”, “Sure, I can help with…”
2. Execute before explaining — code/result first, prose second
3. No meta-commentary — don’t narrate what you’re about to do
4. No preamble — skip the warm-up
5. No postamble — skip the “let me know if you need…” sign-off
6. No tool announcements — silent tool use, only the result matters
7. Explain only when needed — comment on non-obvious decisions, not obvious ones
8. Let code speak for itself — minimize narration around code blocks
9. Errors are things to fix, not narrate — debug silently, report the fix
10. Compress prose, preserve technical artifacts — code/URLs/paths stay byte-perfect

These rules are why Caveman is so portable. The exact same ruleset, dropped into AGENTS.md, CLAUDE.md, or .cursorrules, produces compressed output across all major coding agents.

Benchmarks (Real Numbers)

Caveman’s repo includes tiktoken-verified benchmarks across 10 representative tasks:

Average across all 10 tasks: 65% output reduction.

Memory file compression (running Caveman against existing CLAUDE.md / project notes) reduces input tokens by ~46% on average, which compounds because input tokens are loaded every session.

For a Claude Code user spending $50/month on output tokens, a 65% reduction translates to roughly $17/month after savings — a $33 saving for adding ten lines to AGENTS.md.

Installation Methods

Caveman supports 30+ agents through different delivery mechanisms.

Universal one-liner (Unix-like)

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

Universal one-liner (Windows PowerShell 5.1+)

irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex

The installer detects which agents are present (Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Cline, Copilot, etc.) and configures each appropriately. Node ≥18 required. Re-running is safe.

Per-agent specifics

For agents without auto-activation, users invoke /caveman once per session to opt in.

The Tool Suite

Beyond the core ruleset, Caveman ships several utility commands:

The caveman-shrink middleware is particularly useful — MCP servers often have verbose tool descriptions that bloat every session’s context window. Running them through caveman-shrink reclaims tokens without changing tool functionality.

How Caveman Fits the AGENTS.md Ecosystem

Caveman is content for an existing rule file, not a new rule file format. Here’s the mapping:

Because the rule content is plain markdown prose, it works equally well in any format. The installer’s job is just deciding where to put the file and how to wire it to the right agent.

For deeper coverage of the rule-file landscape, see AGENTS.md vs CLAUDE.md vs .cursor/rules.

The Caveman Ecosystem

Caveman has spawned a small constellation of related projects:

• cavemem — Cross-agent memory compression. Periodically rewrites your CLAUDE.md / project notes in compressed form, automatically.
• cavekit — Spec-driven build loops with caveman compression baked in. Useful for repeatable scaffolding tasks.
• cavegemma — Fine-tuned Gemma 4 31B model with compression baked into the weights. Runs locally, no rule file needed.

For most users, the core caveman install is enough. The ecosystem is for users who want compression to extend beyond Claude/Codex/Cursor into self-hosted models or specialized workflows.

When Caveman Helps vs When It Hurts

Caveman is excellent for:

• Long sessions where output tokens accumulate (refactoring, multi-file edits)
• Cost-sensitive teams running Claude API at scale
• Engineers who already speak in shorthand — caveman matches their preferred style
• CI environments where verbose output makes logs unreadable

Caveman is less useful for:

• Pair-programming sessions where you want the model to “think out loud” — caveman compresses the thinking-out-loud away
• Onboarding new engineers — caveman output is harder to follow if you’re learning what the agent does
• Compliance-heavy workflows that need explicit audit trails of model reasoning
• Customer-facing chat interfaces — caveman style sounds curt to non-engineers

The right answer is toggle it per task: /caveman full for refactor-heavy work, /caveman lite or off for exploratory sessions.

Should You Add Caveman to Your Project’s AGENTS.md?

A practical test: count the number of times in the last week you skim-read a Claude response and thought “just give me the code.” If that’s more than once a day, install Caveman. If you actually read the prose responses end-to-end and find them useful, hold off.

For most production engineering teams in 2026, the answer is yes. The 65% token reduction translates to direct cost savings and faster session iteration, with minimal accuracy cost.

Common Pitfalls

1. Installing globally then forgetting it’s on. New teammates joining your project may be confused by terse responses. Document Caveman in your team README.
2. Using wenyan mode in shared codebases. The classical Chinese variant is fun but unreadable to most teams. Stick with full for shared projects.
3. Compressing CLAUDE.md too aggressively. caveman-compress will rewrite your instructions in caveman style — which compounds compression. Read the output before committing.
4. Forgetting Caveman doesn’t compress code. Some users expect output reduction across the board; only natural-language prose gets compressed, code stays full.
5. Using /caveman with prompt-type hooks. The prompt hook fires a model call expecting a JSON response. Caveman compression can shorten the JSON output of the hook’s model call, but the hook handler itself doesn’t run with Caveman context. Plan accordingly.

FAQ

What is Caveman.MD and how does it differ from AGENTS.md or CLAUDE.md?

Caveman is not a new rule file format. It’s a set of instructions (10 rules + 4 compression levels) that drops into your existing AGENTS.md, CLAUDE.md, .cursor/rules, .windsurf/rules, etc. The instructions tell the model to compress its prose output by 65% on average, while leaving code, URLs, file paths, and technical content byte-perfect.

How much money does Caveman actually save?

In benchmarks, Caveman cuts output tokens by an average of 65% (range 22–87%). For a user spending $50/month on Claude output tokens, that’s roughly $33/month back. Input token compression (via caveman-compress on CLAUDE.md / memory files) saves another ~46% on input, compounding session-over-session.

Does Caveman make Claude less accurate?

No — and possibly the opposite. A March 2026 research paper cited in the Caveman docs reports that “constraining large models to brief responses improved accuracy by 26 points on certain benchmarks.” Verbose preambles correlate with worse, not better, reasoning. Caveman removes the preamble while leaving thinking-token computation untouched.

What’s the difference between lite, full, ultra, and wenyan modes?

lite removes filler words only — output still reads like natural prose. full is the default caveman mode, telegraphic but readable. ultra is maximum brevity, slight readability cost. wenyan mimics classical Chinese style and produces the shortest output (often for fun or pure log-style use).

Does Caveman work with Cursor, Windsurf, Cline, Aider?

Yes — the universal installer detects 30+ supported agents and configures each. Cursor gets .cursor/rules/caveman.mdc with alwaysApply: true. Windsurf gets .windsurf/rules/caveman.md with trigger: always_on. Cline reads .clinerules/caveman.md. Aider reads it via .aider.conf.yml.

Can I use Caveman with the official Claude Code plugin system?

Yes — Caveman ships as a Claude Code plugin installed at ~/.claude/plugins/caveman/. The plugin auto-activates, no per-session opt-in needed. To uninstall, remove the directory and restart Claude Code.

What is caveman-shrink MCP middleware?

A separate utility that compresses MCP server tool descriptions before they enter the context window. MCP servers often have verbose, multi-paragraph tool descriptions that bloat every session’s startup context. caveman-shrink rewrites these in compressed form, recovering tokens without changing tool functionality.

Does Caveman compress my prompt or only the model’s output?

Only output by default. The model’s input (your prompt + CLAUDE.md + tool descriptions) is unchanged unless you explicitly run caveman-compress against memory files or caveman-shrink against MCP descriptions. The cost-saving is mostly on the output side, which is also where models are most prone to filler.

Can I add Caveman rules manually instead of using the installer?

Yes. The repo’s README lists the 10 rules verbatim — copy them into your AGENTS.md (or CLAUDE.md, or .cursor/rules/caveman.mdc) as plain markdown. The installer is just a convenience for wiring multiple agents at once.

Related Articles

• AGENTS.md vs CLAUDE.md vs .cursor/rules: Three-Way Comparison
• Claude Code Subagents: The Complete 2026 Reference
• Claude Code Hooks: The Complete 2026 Production Reference
• 15 Best Claude Code Skills You Should Install in 2026
• Browse 165+ Real AI Coding Rules

External References

• JuliusBrussee/caveman on GitHub
• Caveman CLAUDE.md rule listing on PS