github.com/JuliusBrussee/caveman
Chat with this repoBrowse by type
What it actually does AI analysis from the code graph — generated when you open this
README
why use many token when few do trick
You pay for AI by the token, and your agent writes like it knows that.
Caveman make agent stop. Same brain. Fewer words. Smaller bill.
See it · Install · Savings · Learn · Proxy · Wrap · Docs · License
See it
| 🗣️ Normal agent — 69 tokens |  Caveman agent — 19 tokens |
|---|---|
| > The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object. | > New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`. |
Nothing of value died in the second answer. The diagnosis survived, the fix survived, the useMemo survived; only the throat-clearing went. That's 50 tokens back on one reply, and an agent produces a few hundred replies a day.
Code, commands, file paths, and exact error messages never get cavemanned. Only the prose around them does.
Install
Caveman comes in two sizes.
The small one is the skill: a rule file that makes your agent answer in caveman. Free forever, MIT, runs in 30+ agents (Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, Copilot, more), installs in one command:
npx skills add JuliusBrussee/caveman
Type /caveman in your agent if it doesn't wake up on its own. That the whole install. One rock.
The big one is the proxy. It sits between your agent and the AI provider, on your machine, and shrinks what the agent reads before every call; a copy of anything it compressed stays on your disk in case the agent needs the original back. MIT CLI, BSL-1.1 runtime:
npm install -g @caveman-ai/cli && caveman setup --install
caveman claude # or codex · gemini · aider · kilo · qwen · opencode · hermes · openclaw · pi
They stack. Most people start with the skill and graduate.
More doors into the cave — full installer, Windows, single agents, uninstall
The full installer wires up Claude Code hooks and the statusline badge, detects every supported agent on your machine, and reruns safely (Node.js 22.13+):
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.6.0/install.sh | bash
On Windows (PowerShell 5.1+):
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.6.0/install.ps1 | iex
Just one agent:
# Claude Code
claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman
# Gemini CLI
gemini extensions install https://github.com/JuliusBrussee/caveman
# Qwen Code CLI, then its Caveman wrapper
npm i -g @qwen-code/qwen-code
caveman qwen
# Codex, Cursor, Windsurf, Cline, and other skills-compatible agents
npx skills add JuliusBrussee/caveman --skill '*' -a codex --yes # replace codex with your agent profile
Changed your mind: npx -y github:JuliusBrussee/caveman -- --uninstall.
The full 30+ agent matrix, dry runs, flags, and verification live in INSTALL.md.
What you save
Quick vocabulary, since tokens are the whole point: a token is the unit AI billing runs on, roughly three-quarters of a word. Your agent spends them twice, once on everything it writes and again on everything it reads, and the reading is usually the bigger half of the bill. Caveman goes after both.
Writing less
Ten ordinary coding prompts through the real Claude API, with the skill and without. Same model, same questions; the only change is caveman telling it to keep it short:
The numbers behind the chart — regenerate with uv run python benchmarks/run.py
| Task | Normal | Caveman | Saved |
|---|---|---|---|
| Explain React re-render bug | 1180 | 159 | 87% |
| Fix auth middleware token expiry | 704 | 121 | 83% |
| Set up PostgreSQL connection pool | 2347 | 380 | 84% |
| Explain git rebase vs merge | 702 | 292 | 58% |
| Refactor callback to async/await | 387 | 301 | 22% |
| Architecture: microservices vs monolith | 446 | 310 | 30% |
| Review PR for security issues | 678 | 398 | 41% |
| Docker multi-stage build | 1042 | 290 | 72% |
| Debug PostgreSQL race condition | 1200 | 232 | 81% |
| Implement React error boundary | 3454 | 456 | 87% |
| Average | 1214 | 294 | 65% |
[!IMPORTANT] Before you multiply 65% by your invoice: the skill only shortens output. Input and reasoning tokens don't change, and the skill's own rules cost about 1–1.5k input tokens every turn, so whole-session savings land lower than the chart, and on workloads that were already terse you can lose money. Speed and readability are the real product; the discount is the bonus. The full accounting, including the cases where caveman loses, is in docs/HONEST-NUMBERS.md.
Reading less
An agent rereads logs, test output, diffs, and half your repo all day long, which is why input dwarfs output on most invoices. The proxy compresses that stream. In a pinned 54-run Claude Code benchmark it used 33.2% fewer provider-reported input tokens than direct Claude Code and passed all 18/18 exact-answer checks, so the squeeze cost nothing in correctness:
One case got worse, and it's on the chart: HTML had no compression transform, so caveman paid its own overhead and won nothing back. Losses stay visible here. Method, confidence intervals, and limits: docs/WRAP-BENCHMARK.md benchmark_counterfactual
Browsing gets the same treatment. A focused question against a 200-row operations table costs 121 tokens through caveman's compressed view of the page; the Playwright ARIA baseline spends 15,704 on the same answer, which makes caveman 129.8× smaller there (browse/BENCHMARK.md).
Where your tokens go
You don't have to guess whether any of this applies to you. Months of your agent history already sit on your disk, and caveman learn will read it: local, read-only, no account.
caveman learn # Claude Code + Codex + Gemini CLI + opencode; aider via CAVEMAN_AIDER_ROOT
Out comes a Cave Score, your token sinks ranked worst-first with a one-line fix behind each, how deep each session ran into its context window, a replay of what the fixes would have saved you, and a list-price estimate of what those sinks cost over 30 days.
Ready to act on it?
caveman learn implement # hand the plan to Claude Code or Codex
That opens your own agent with the plan and one rule it must follow: propose each fix as a diff, apply only on your yes, re-measure, and revert anything that didn't lower tokens per turn. Caveman never makes your agent dumber to make it cheaper.
Caveman Proxy
The proxy is one local process. Your agent talks to it, it talks to your provider, and nothing about your account changes; Claude Pro/Max OAuth credentials pass through to Anthropic untouched. There is no Caveman backend in the path. Originals of everything it compresses live in a SQLite file on your machine, each with a recovery handle, so the agent can always pull back what caveman squeezed.
caveman claude # or any of the ten wrapped agents
What the engine keeps, by payload type — and the wrap stack diagram
detect() types each payload and routes it to a compressor that keeps what answers depend on:
| Detected type | Keeps | Target savings |
|---|---|---|
json |
keys, structure, error/message subtrees; collapses repetitive arrays | 70–90% |
log |
errors, stack traces, first/last lines; drops INFO and progress noise | 85–95% |
code |
imports, signatures, types; elides function bodies, syntax stays valid | 40–70% |
diff |
file/hunk headers and changed lines; elides repeated context | 60–80% |
search-result |
top/bottom hits plus diagnostic/security hits | 80–95% |
text / HTML |
headings, opening/closing context, important sections | 50–80% |
contextwindow.Pack() additionally fits candidate context into a token budget by BM25 relevance, recency, and error signal, returned in original order so chronology survives.
The same engine answers to a set of verbs:
caveman learn # scan your real agent history → score + ranked token sinks
caveman learn implement # fix the findings with your own agent, consent-gated per edit
caveman explore install # read-only FastContext subagent: finds code as path:line
caveman shrink -- pnpm test # compress noisy command output, byte-exact recoverable
caveman browse <url> # local Chrome over a compressed a11y tree
caveman mem remember|recall # durable memory; `mem recover <handle>` = original bytes
caveman trial -- claude # A/B a real session, then `trial report`
caveman toon encode|decode # the TOON re-encoder, standalone
caveman stats # what caveman actually did, by content type
Any MCP host gets the same powers through five tools: caveman_compress, caveman_retrieve, caveman_stats, caveman_toon_encode, caveman_toon_decode.
Pixel mode
Caveman eating its own tail. Every skill you install, this one included, is prompt text your agent reloads on every single invocation, and you pay that tax forever. caveman convert renders an installed skill's body to PNG pages in place; the frontmatter stays text so discovery and triggering keep working, and the model reads the body as an image.
```bash caveman convert --dry-run # every installed skill, with the token math, no writes caveman
Extension points exported contracts — how you extend this code
browse all types & interfaces →
Core symbols most depended-on inside this repo
Shape
Languages
Modules by API surface
Dependencies from manifests, versioned
Datastores touched
For agents
$ claude mcp add caveman \
-- python -m otcore.mcp_server <graph>