Caveman: a skill and proxy that cut Claude Code output tokens by 65%
A skill and local proxy that make Claude Code–style agents use fewer words by compressing output and reads while keeping original backups.
GitHub JuliusBrussee/caveman Updated 2026-09-04 Branch main Stars 112.5K Forks 6.5K
Claude Code Token cost optimization Node.js 22.13+ Go / JavaScript / TypeScript / Python / Shell

🧭 Decision Guide

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?
For: An independent developer tracking API costs across output, input, and reasoning tokens while using Claude Code for long multi-turn coding sessions

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-stats to 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
Not stated in the README:The README does not say whether `/caveman-stats` accurately covers provider-side reasoning tokens and final billing;It provides no total-cost data for your model, repository size, or multi-turn session length;It does not quantify latency or retry costs introduced by Proxy compression
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?
For: A senior developer using Claude Code for code review, security fixes, and database migrations who worries that ultra mode may hide risk details

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, and ultra intensities; ultra optimizes 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, and verify-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
Not stated in the README:The README does not define the exact compression rules for `ultra`, `full`, and `lite` during security reviews;It provides no review-accuracy, missed-risk, or migration-failure measurements
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?
For: An independent developer who uses Claude Code for frequent React explanations and debugging, and wants shorter responses

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 useMemo fix.
  • 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, and off modes, 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
Not stated in the README:The README does not provide total billing savings for your specific React project and multi-turn sessions;It does not specify compatibility details for your current Claude Code version
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?
For: An engineering lead who can run Node.js 22.13+, needs local context compression between agents and providers, and must review the BSL-1.1 commercial license

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
Not stated in the README:The README does not specify the backup directory, encryption, retention period, or cleanup command;It does not determine how BSL-1.1 applies to your specific commercial integration and redistribution model;It does not provide a Proxy security audit or performance-overhead figures
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?
For: A developer on Windows PowerShell 5.1+ who mainly runs Gemini CLI and Qwen Code and wants to avoid configuring multiple agents manually

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.ps1 command 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 qwen wrapper, 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
Not stated in the README:The README does not define hook and statusline support for Gemini CLI and Qwen Code on Windows;It does not specify PowerShell execution-policy, proxy-network, or enterprise-device permission requirements
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?
For: A member of a small engineering team using Claude Code, Codex, Gemini, Cursor, and Windsurf who wants one shared agent configuration

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 as investigate-first, safe-refactor, and migration, enabling a common workflow vocabulary.
  • The README also gives agent-specific installation commands, such as npx skills add ... -a codex --yes for 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
Not stated in the README:The README does not establish that commands, subagents, and work patterns behave identically across agents;It does not provide a team-wide shared configuration, version-locking, or centralized policy mechanism

✨ 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