JuliusBrussee/caveman

Caveman – Token‑saving wrapper for AI coding agents

What it is – Caveman is a lightweight “skill” (a rule file) and an optional local proxy that sit between your AI‑powered coding assistant (Claude Code, Codex, Gemini, Cursor, etc.) and the underlying LLM provider. Its sole purpose is to shrink the amount of text the model has to read and write, thereby lowering the number of tokens that get billed.

How it works

• Skill (small rock) – a simple prompt‑style rule that rewrites the prose part of the model’s replies in a terse, “caveman” style (e.g., turning a 69‑token explanation into 19 tokens). Code snippets, file paths and exact error messages are left untouched.
• Proxy (big rock) – a local Node.js process that intercepts every request from the agent to the LLM provider. It detects the payload type (JSON, logs, code, diffs, search results, etc.) and applies a custom compressor that keeps the essential information (keys, error lines, function signatures, etc.) while discarding repetitive or noisy parts. The original payload is stored in a SQLite cache so the agent can retrieve the full text on demand.
• Wrap‑any‑agent – a thin wrapper that launches the target agent with the proxy enabled, without modifying the agent’s configuration files. Supported agents include Claude Code, OpenAI Codex CLI, Gemini CLI, Aider, Kilo Code, Qwen Code, opencode, Hermes, OpenClaw, and Pi.

Key numbers from the README

• Writing‑side savings – on ten typical coding prompts the skill reduced output tokens from an average of 1,214 to 294, a 65 % reduction.
• Reading‑side savings – on a 54‑run Claude Code benchmark the proxy cut input tokens from 885,793 to 591,673, a 33 % drop overall (some cases, like a pure‑HTML page, saw a small increase).
• Compression ratios – JSON payloads shrink 70‑90 %, logs 85‑95 %, code 40‑70 %, diffs 60‑80 %.

Installation

1. Skill only – one‑liner via the skills CLI:

   npx skills add JuliusBrussee/caveman
   

   Then invoke /caveman inside your agent (or type /caveman if the agent doesn’t auto‑load it).
2. Proxy – global npm install and setup:

   npm install -g @caveman-ai/cli && caveman setup --install
   caveman claude   # or codex, gemini, etc.
   

   A full installer script is also provided for macOS/Linux (install.sh) and Windows PowerShell (install.ps1).

Typical workflow

1. Run caveman <agent> (or caveman wrap <agent>) to start the chosen coding assistant with the proxy active.
2. The agent asks the LLM for help; the proxy compresses any large context (logs, diffs, JSON) before sending it upstream.
3. The LLM’s reply is post‑processed by the skill, turning verbose explanations into terse sentences while leaving code untouched.
4. Use helper commands such as:
   • /caveman-commit – terse Conventional Commit messages
   • /caveman-review – one‑line code review notes
   • caveman compress <file> – shrink large markdown files locally
   • caveman stats – see token‑usage statistics for the current session
   • caveman learn – analyses past sessions on disk and suggests where token waste occurs.

Why you might want it

• Cost reduction – if you pay per token (e.g., Anthropic, OpenAI), cutting both input and output can noticeably lower your bill, especially on long‑running debugging sessions that involve large logs or diffs.
• Speed – smaller payloads mean less data transferred and faster round‑trips.
• Privacy – the proxy stores original data locally; only the compressed version is sent to the provider.

Caveats / Limitations

• The skill only shortens prose; it does not reduce the tokens spent on the model’s reasoning or on the input context that the proxy cannot compress.
• Compression adds its own overhead (≈1‑1.5 k input tokens per turn) which can offset savings on already terse interactions.
• Certain payload types (e.g., pure HTML) may see a net increase because the compressor has little to trim.
• The tool is a “wrapper” – it does not modify the underlying agent’s code, but it does require Node 22+ and a compatible CLI for each supported agent.
• The README notes that the token‑saving claims are benchmarks; real‑world savings will vary and should be measured with caveman stats or a custom A/B trial.

License – The skill component is MIT‑licensed and free forever; the proxy runtime is dual‑licensed MIT + BSL‑1.1.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.