🧭 Decision Guide
Why trending now: The repository gained 543 stars on GitHub Trending that day. The README highlights a 65% average output-token reduction across ten real Claude API prompts, and the latest release is v2.6.0. These are visible attention signals, but the specific cause cannot be confirmed from the material.
Try it if you
-
Your Claude API tasks often produce long explanations, such as React error boundaries or PostgreSQL connection pools.The README's “The numbers” section reports 87% and 84% savings for these tasks respectively.
-
You use Claude Code, Codex, Gemini, Cursor, or another skills-compatible agent.The README's “Install” section says the skill works with 30+ agents and lists these agents.
-
You want to compress both agent output and the context it reads.The README's “The numbers” section says the skill cuts writing and the proxy cuts reading; “Big rock: the proxy” says it compresses read content.
Skip it if you
-
Your work mainly produces already-terse code answers, such as refactoring callbacks to async/await.In “The numbers,” that task saves only 22%, and the README says already-terse answers may provide little benefit.
-
You treat 65% as a direct discount for the entire session or invoice.The README's IMPORTANT note says input and reasoning tokens do not change, so whole-session savings are lower than the table.
-
Your deployment policy allows only MIT components and cannot accept a BSL-1.1 runtime.The README's Install and License sections state that the skill is MIT while the proxy engine/runtime is BSL-1.1.
Requirements
- The full installer requires Node.js 22.13+.
- Skill installation depends on npx; the proxy installs @caveman-ai/cli through npm.
- The proxy runs locally between the coding agent and the AI provider.
- The README's experiment uses the real Claude API and ten coding prompts.
First step (verbatim from README)
npx skills add JuliusBrussee/caveman
Watch out
-
Do not multiply the skill's output savings directly into the invoice; the README says its rules add 1–1.5k input tokens per turn.The IMPORTANT note below “The numbers.”
-
If the agent does not wake Caveman automatically, type /caveman.The README's “Install” section explicitly says to type /caveman manually.
-
The full installer adds Claude Code hooks and a statusline badge, and requires Node.js 22.13+.The full-installer paragraph in the README's “Install” section.
-
The maintainer reports an opposite and unreproducible Cursor A/B result and points readers to HONEST-NUMBERS.md.The README's Maintainer note and linked issue #550.
Not stated in the README
- The README provides no independent token comparisons for different models, providers, or non-Claude APIs.
- The README does not quantify how proxy read compression affects latency, accuracy, or context completeness.
- The README does not explain the specific commercial restrictions, change date, or future licensing plan for the BSL-1.1 runtime.
- The README does not provide the complete 30+ agent behavior matrix, version compatibility matrix, or test coverage by agent.
- The README does not state the default path, retention period, encryption method, or sensitive-data handling for disk backups.
- The README does not provide the complete inputs, execution environment, or invoice-level cost details for the ten benchmark prompts.
💡 Deep Analysis
6
No
I use Claude Code for long multi-turn coding tasks, and my bill depends on input, output, and reasoning tokens. Can I infer lower total cost from the README’s 65% output-savings figure?
No, you should not infer lower total cost from 65%, because that number describes output savings in a specific benchmark.
- The README’s “The numbers” section separates tokens the agent writes from tokens it reads and says reading is usually the larger billing source.
- The project insight says 65% came from output comparisons across ten specific tasks, with input and reasoning tokens unchanged; the Skill itself also adds roughly 1,000–1,500 input tokens.
- The Proxy targets input-context compression, with project data reporting about 33% input-token savings, but that is not a guarantee for every agent, model, or session.
- The project provides
/caveman-statsto inspect local Claude Code session usage and estimated savings. That is more relevant than multiplying 65% by your bill.
- README, “The numbers”: “Your agent pays for every token it writes and every token it reads”; reading is usually the bigger bill
- Project insight, “innovation_points”: 65% is output savings in a specific benchmark, while the Skill adds roughly 1,000–1,500 input tokens
- Project insight, “key_features”: the Proxy compresses input context; reported input-token savings are about 33%
- README, “The skill, unpacked”: `/caveman-stats` reports local Claude Code session usage and estimated savings
/caveman-stats
No
I use Claude Code for code review, security fixes, and database migrations, and I must see assumptions, risks, and verification results. Can I make `/caveman ultra` my default mode?
No, ultra should not be your default because your tasks require complete risk disclosure, while the project explicitly warns that aggressive compression can become too terse.
- The Skill provides
lite,full, andultraintensities;ultraoptimizes brevity rather than producing a complete review record. - The project insight says ultra-like modes may omit explanations, assumptions, risks, or verification results.
- Its limitations specifically call out security reviews, production migrations, and high-risk operations: optimizing for short answers can remove necessary reasoning and warnings.
- You can still use
safe-refactor,migration, andverify-and-stop, but the README does not guarantee that these modes emit every audit field you require.
- README, “The skill, unpacked”: `lite|full|ultra` modes and `safe-refactor`, `migration`, and `verify-and-stop`
- Project insight, “common_pitfalls”: ultra may omit explanations, assumptions, risks, or verification results
- Project insight, “usage_limitations”: security reviews, production migrations, and high-risk operations should not over-optimize for brevity
npx skills add JuliusBrussee/caveman
Yes
I mainly use Claude Code to debug React components. I want to preserve code, commands, and exact error messages while shortening only the explanatory prose. Is Caveman’s Skill suitable for me?
Yes, the Skill fits because it compresses the agent’s wording without rewriting code or exact error messages.
- The README’s React example reduces a normal explanation from 69 tokens to 19 while preserving the same diagnosis and
useMemofix. - It explicitly says, “Code, commands, file paths, and exact error messages never get cavemanned,” which matches your debugging constraint.
- Claude Code is supported, and the Skill offers
lite,full,ultra, andoffmodes, so you do not have to begin with the most aggressive setting. - However, the rule file itself adds input tokens. The README’s 65% figure concerns output savings, not guaranteed total-session or billing savings.
- README, “See it”: React example drops from 69 tokens to 19 tokens
- README, “See it”: “Code, commands, file paths, and exact error messages never get cavemanned”
- README, “The skill, unpacked”: `/caveman lite|full|ultra...|off`
- Project insight: the Skill itself adds roughly 1,000–1,500 input tokens
npx skills add JuliusBrussee/caveman
It depends
I can upgrade the environment to Node.js 22.13+, but the agent reads source code and logs, and our commercial product must review the BSL-1.1 license. Should I enable Caveman Proxy?
It depends: the runtime prerequisite is achievable, but sensitive-data governance and the commercial license may still rule out the Proxy.
- The README says the Proxy runs between the agent and the AI provider and compresses what the agent reads before each call, directly targeting input-context usage.
- Compressed content is backed up on local disk so the agent can recover the original. Source code, logs, or data near credentials could therefore be stored locally.
- The full installer requires Node.js 22.13+, and the licensing differs: the CLI is MIT while the runtime is BSL-1.1.
- If your organization cannot accept local raw-content backups, a middle-layer proxy, or BSL-1.1, do not enable the Proxy directly; the MIT Skill is a narrower alternative.
- README, “Install”: the Big rock runs on your machine, between your agent and the AI provider
- README, “Install”: “Everything it squeezes gets a backup on your disk”
- README, “Install”: requires Node.js 22.13+; MIT CLI, BSL-1.1 runtime
- Project insight, “usage_limitations”: local backups may contain source code, logs, or business data
npm install -g @caveman-ai/cli && caveman setup --install
Yes
I use Gemini CLI and Qwen Code on Windows PowerShell 5.1+ and want one installation path plus Caveman entry points for both. Does the README support this environment?
Yes, the README supports this setup with a Windows installer, a Gemini extension path, and a Qwen Code package-plus-wrapper path.
- The Windows route explicitly requires PowerShell 5.1+ and provides an
install.ps1command pinned to v2.6.0. - Gemini CLI has its own command,
gemini extensions install https://github.com/JuliusBrussee/caveman, rather than using the Claude Code plugin flow. - Qwen Code is installed with npm and then launched through the
caveman qwenwrapper, matching the unified CLI entry points listed in the README. - However, the full installer discovers agents and configures hooks and a statusline. The README does not say whether those extras behave identically for Gemini and Qwen on Windows.
- README, “Install”: Windows, PowerShell 5.1+
- README, “Just one agent”: `gemini extensions install https://github.com/JuliusBrussee/caveman`
- README, “Just one agent”: `npm i -g @qwen-code/qwen-code` and `caveman qwen`
- README, “Install”: the full installer wires up hooks and statusline and needs Node.js 22.13+
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.6.0/install.ps1 | iex
Yes
Our team uses Claude Code, Codex, Gemini, Cursor, and Windsurf in the same workflow. We do not want to maintain separate prompt rules for each agent. Can Caveman provide one shared Skill entry point?
Yes, provided the agents can all accept a shared concise-response policy.
- The README says the Small rock works with 30+ agents and explicitly lists Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, and Copilot.
- The same Skill exposes
/caveman,/caveman-review,/caveman-commit, and work patterns such asinvestigate-first,safe-refactor, andmigration, enabling a common workflow vocabulary. - The README also gives agent-specific installation commands, such as
npx skills add ... -a codex --yesfor Codex. This indicates shared Skill content, but potentially different deployment entry points. - If the team requires agent-specific output schemas or completely separate prompt governance, Caveman’s common rules may be too coarse.
- README, “Install”: works in 30+ agents, including Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, and Copilot
- README, “The skill, unpacked”: lists `/caveman-review`, `/caveman-commit`, and multiple work patterns
- README, “Just one agent”: `npx skills add JuliusBrussee/caveman --skill '*' -a codex --yes`
npx skills add JuliusBrussee/caveman --skill '*' -a codex --yes # replace codex with your agent profile
✨ Highlights
-
Ten Claude API prompts used 65% fewer output tokens on average
-
Supports 30+ agents including Claude Code, Codex, and Gemini
-
The proxy compresses read content and keeps originals backed up on disk
-
The skill uses MIT while the runtime uses BSL-1.1
🔧 Engineering
-
Use /caveman lite through ultra to control response compression
-
The proxy compresses agent-read content before each call and backs up originals
-
cavecrew presets compress investigator, builder, and reviewer subagents
-
Use /caveman-stats to inspect Claude Code session tokens
⚠️ Risks
-
The 65% figure covers output only, while rules add about 1–1.5k input tokens per turn
-
Input and reasoning do not change, so whole-session savings are below the table figures
-
The README says already-terse responses can result in higher costs
-
The proxy runtime is BSL-1.1, not MIT-licensed
👥 For who?
-
Developers using Claude Code, Codex, or Gemini CLI
-
Teams frequently handling long React and PostgreSQL explanations or debugging tasks
-
Users who can install Node.js 22.13+ and accept a local proxy