JuliusBrussee/caveman

Caveman – Token‑saving layer for AI coding agents

What it is

• A CLI‑based proxy that sits between you and any LLM‑powered coding assistant (Claude, Gemini, OpenAI, etc.) and rewrites the answers and inputs to be much shorter while keeping the exact code and meaning.
• It works as a “rock” that can be turned on/off for six independent features:
  1. Say less – forces the model to answer in a terse, controlled‑English style (e.g., New object ref each render, so React re‑renders. Wrap the prop in useMemo.) reducing output tokens.
  2. Read less – compresses logs, CSV, JSON, YAML, test output, etc., before the model reads them, cutting input tokens by ~33 % on typical sessions.
  3. Auto – automatically picks the cheapest model and effort level for each request, saving ~54 % cost compared with a high‑effort Claude Opus run.
  4. Blocks – a code‑mode cache that stores scripts an agent repeatedly writes, re‑using them instead of re‑generating, dropping token usage from hundreds to dozens per run.
  5. Waste fixes – analyses past sessions to locate token‑heavy patterns and suggests fixes; also keeps Anthropic prompt caches warm while you pause.
  6. Browse – fetches web pages and returns a heavily compressed version (e.g., 121 tokens vs 15 k raw).

Why it matters

• LLM pricing is usually per‑token; cutting both input and output tokens can halve or more the cost of a coding session without degrading answer quality (the repo cites A/B tests with Adobe Research, JetBrains, and Elastic showing no measurable quality loss).
• The tool is model‑agnostic: once installed it automatically wraps Claude, Gemini, OpenAI, and >30 other agents.

Installation

npx @caveman-ai/cli@latest   # one‑liner, works on macOS, Linux, Windows (Node 22.13+)

• The installer discovers your agents, asks for any needed logins, and then activates all six rocks by default.
• You can later toggle individual rocks with caveman on|off <rock> or disable the whole proxy.

Core commands

Command	Purpose
caveman claude	Start a coding session with Caveman enabled for any supported agent.
caveman status	Show which rocks are active and which agents are wrapped.
`caveman on	off `
cavelon learn	Analyse your token usage history and suggest fixes.
/caveman, /ultracave, /megacave	In‑chat shortcuts that switch the answer style (different token budgets, multilingual).
/caveman‑compress <file>	Compress a local file (logs, JSON, etc.) before the model reads it.
caveman‑blocks scan	List scripts the agent rewrites repeatedly; blocks let the agent reuse them.

Evidence of impact

• 33.2 % fewer input tokens across a mixed suite of CSV, logs, YAML, JSON, and test output.
• 54 % lower cost on a 85‑task coding benchmark when using Auto.
• 397 → 76 tokens for a single test‑run script when Blocks are applied.
• Independent validation by Adobe Research (1.4‑2.4× cost reduction), JetBrains (no quality loss), and Elastic (63.6 % fewer response tokens).

Who should use it

• Developers who rely on LLM‑powered code assistants and want to keep their API bills low.
• Teams deploying internal AI agents (the Caveman Cloud add‑on provides observability, evals, and autopilot suggestions for production agents).
• Anyone comfortable with a Node‑based CLI and willing to let a thin proxy rewrite model output for brevity.

Links

• Docs & install guide: ./INSTALL.md
• Full benchmark details: ./docs/WRAP-BENCHMARK.md, ./docs/AUTO‑BENCHMARK.md
• Cloud product: https://caveman.so