JuliusBrussee/cavemanPublic

why use many token when few do trick

Your AI coding agent bills by the word and writes like it knows that. Caveman make it stop.

▶️ ThePrimeagen reacts: "No way this actually works"

🏆 #1 on GitHub Trending · July 2026  ·  🥇 #1 Repository of the Day on Trendshift · April 2026

#1 on Hacker News  ·  #8 Product of the Day

📄 Cited in CAVEWOMAN, an Adobe Research paper that measured caveman-style output cutting cost 1.4 to 2.4×, up to 3×  ·  🧪 Tested by JetBrains on 86 real coding tasks: "costs you nothing measurable in quality"

⚡ One command, no account, no API key. npx skills add JuliusBrussee/caveman -g → Quick Start

🗣️ 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.

Same diagnosis. Same fix. Same useMemo. The only thing that died was the throat-clearing.

Code, commands, file paths, and exact error messages never get cavemanned. Only the prose around them does. Security warnings and "are you sure?" confirmations come back in full sentences on their own, then caveman resumes.

Caveman no make brain smaller. Caveman make mouth smaller.

Half the fun is that your agent talks like it just discovered fire. The other half is that it is still right.

A token is what AI billing counts, roughly three quarters of a word. Your agent pays for every token it writes and every token it reads. Most agents write like a cover letter and read like a firehose.

Caveman attacks both ends, in the agent you run and in the one you build:

• The skill shrinks what the agent says. One rule file. Free forever. Works in 30+ agents.
• The proxy shrinks what the agent reads: logs, test output, JSON, diffs, search results. Runs on your machine. Every squeezed byte gets a backup, so the agent can always pull the original back.
• The middleware does the same inside your own code: one wrapper around the LangChain, Vercel AI SDK, OpenAI, or Anthropic call you already make. Tool results get shrunk before the model sees them, the original stays in your history, and the model can fetch it back.

Started as a joke on a Friday in April 2026. Hit 4,000 stars in a week. Now past 100,000, with a research paper, a JetBrains lab test, and a Primeagen reaction video. The joke got serious. The voice did not.

Caveman come in two sizes. Start small.

A rule file that makes your agent answer in caveman. Apache-2.0, free forever, works in 30+ agents (Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, Copilot, more). One command:

npx skills add JuliusBrussee/caveman -g

Type /caveman if your agent doesn't wake up on its own. That the whole install. One rock.

Runs on your machine, between your agent and the AI provider, and shrinks what the agent reads before every call. Apache-2.0, CLI and runtime both:

npm install -g @caveman-ai/cli && caveman setup --install
caveman claude        # or codex · gemini · aider · kilo · qwen · opencode · hermes · openclaw · pi

Building an agent in code instead of running one in a terminal? Same shrinking, one wrapper around the call you already make. Apache-2.0 client, stable 1.0:

npm install @caveman-ai/middleware @caveman-ai/sdk        # TypeScript, plus your framework (ai, openai, …)
pip install 'caveman-middleware[langchain]' caveman-sdk   # Python 3.11+, swap the extra for your framework

Six lines of code and a local runtime. Full walkthrough below.

They stack. Most people start with the small rock and graduate.

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v3.0.0/install.sh | bash

irm https://raw.githubusercontent.com/JuliusBrussee/caveman/v3.0.0/install.ps1 | iex

# Claude Code
claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

# Gemini CLI
gemini extensions install https://github.com/JuliusBrussee/caveman

# Oh My Pi (OMP)
npx -y github:JuliusBrussee/caveman -- --only omp

# 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 -g  # replace codex with your agent profile

The full 30+ agent matrix, dry runs, flags, and verification live in INSTALL.md.

Small rock. The skill, right after npx skills add:

1. Ask it something. Any coding question. Watch the preamble vanish and the answer stay.
2. Turn the dial. /caveman lite for tight-but-polite. /caveman ultra for grunts. /caveman wenyan for classical Chinese, because someone asked.
3. Commit like a caveman. /caveman-commit writes a Conventional Commit in one line.
4. Review like a caveman. /caveman-review gives one finding per line: L42: 🔴 null deref. Guard it.
5. Shrink your memory files. /caveman-compress CLAUDE.md cuts the prose, keeps every heading, path, and command, and backs up the original.
6. Come home. Say stop caveman. Normal prose returns. No hard feelings.

Big rock. The proxy, right after npm install -g @caveman-ai/cli:

1. Find out where your tokens go. caveman learn reads months of agent history already on your disk, locally, and ranks the places your tokens go, biggest first, with a one-line fix behind each. Do this before anything else. It is the most useful five minutes in this README. After step 3 it keeps watching by itself and speaks up only when something new appears.
2. Let it fix them. caveman learn implement hands each fix to Claude Code or Codex one diff at a time, applied only on your yes, and undoes anything that did not make each message smaller.
3. Wrap your agent. caveman claude (or codex, gemini, aider, opencode, pi, …) puts the proxy in front of it. Logs, test output, JSON, and diffs get shrunk before the provider sees them. Originals stay on disk, and the agent can pull any of them back.
4. Shrink the noisy stuff. caveman shrink -- pnpm test compresses command output. caveman browse <url> gives the agent a compressed view of a web page instead of a 15,000-token accessibility dump.
5. Prove it on your own work. caveman trial -- claude runs a real session with and without caveman, then caveman trial report shows the difference. That A/B outranks every number on this page. A trial needs its own proxy, so if you already did step 3 it will tell you to run caveman disable claude first, and caveman enable claude after. Caveman rather say "cannot measure this" than hand you a report full of zeros.
6. Shrink caveman itself. caveman convert --dry-run shows which installed skills get cheaper as PNG pages the model reads as an image. Convert the profitable ones, revert byte-for-byte any time.
7. Watch the bill. caveman stats for history and estimates. /caveman-stats inside Claude Code for that session.

Every number below is either from a committed run in this repo or from a named third party. Nothing rounded up. Where a number is small, it says so. Where a row is red, it stays red.

Read those three together and you get the honest picture. Chat-style Q&A: big cut. Agentic coding sessions, where most tokens are code and tool calls that the skill never touches: high single digits on output, quality flat.

The JetBrains number is why the proxy exists. They measured the skill alone, in July 2026, before the proxy shipped. Their finding was that an agent's bill is mostly reading, not writing, and no talking style fixes that. So we built the thing that shrinks the reading. The table below is what that changed.

The Adobe paper's other finding matters too: compressing the human's prompt into caveman-speak makes models answer longer and worse. Caveman never rewrites your prompts. Only the agent's mouth.

The rules add input tokens on every call, and whether shorter output pays for them depends on your agent, caching, and billing. Full accounting: docs/HONEST-NUMBERS.md.

No reviewed API benchmark result is published here yet. Run uv run python benchmarks/run.py to generate a new result, then review its raw response pairs and quality before publishing the generated table.

Your agent rereads logs, test output, diffs, and half your repo all day. The proxy shrinks that stream before it reaches the provider. Pinned 54-run Claude Code benchmark, provider-reported input tokens, three runs per case, every answer checked against an exact oracle:

18 of 18 answer checks passed. Case-clustered 95% interval: 14.6% to 48.5%. In the same suite, Headroom's wrap saved 6.7% and failed 3 of 18 checks. Method, provenance hashes, and limits: docs/WRAP-BENCHMARK.md. Raw harness artifacts are not in this checkout, so treat it as a pinned report, not a public reproduction.

Maintainer note. The HTML row is red and it stays red. That case had no compression transform, so caveman paid its own overhead and won nothing back. The day I hide a red row is the day you should stop trusting the green ones.

Many tool in valley promise small token. They work at different layers, so first what each one touches, then what got measured. Every quote below is from that tool's own README or GitHub page on 2026-09-19.

The one place two of these tools ran side by side against the same known-right answers. Claude Code 2.1.223, claude-sonnet-5, Headroom 0.33.0, six agent-shaped workloads, three runs each, provider-reported input tokens:

Caveman used fewer tokens in 15 of the 18 paired runs. Headroom's 703,202 covers only the 15 runs it answered right, so its 6.7% is against those same 15 direct runs, not against the 885,793 total. Its three failed YAML runs stay in the table and count for nothing. Caveman's one red row, HTML at +9.9%, is in the per-case table above and stays red too. We ran this ourselves, and the raw harness artifacts are not published yet, so it is a pinned report, not something you can re-run from this repo. Method and hashes: docs/WRAP-BENCHMARK.md.

RTK, context-mode, and pxpipe were not in that run. RTK rewrites shell output, and this suite hands the agent its data through a tool call, not the shell, so RTK would have sat idle. Different layer, different test. Fair is fair on the rest: RTK's telemetry is opt-in and ours is opt-out, context-mode sends nothing anywhere, and pxpipe ran SWE-bench where we have not. Stack them if you like. Headroom's own README lists caveman as something it happily runs behind.

One rule file, one talking style, plus a small toolbox. /caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra sets intensity. /caveman off or normal mode turns it off.

Three things the skill will never do: shorten your code, paraphrase an error message, or grunt through a security warning. It drops to full sentences for anything irreversible, then picks the club back up.

One local process. Your agent talks to it, it talks to your provider. No Caveman server in the path, and your Claude Pro/Max login passes through to Anthropic untouched. Originals of everything it compresses sit in a SQLite file on your machine with a recovery handle, so the agent can always ask for the full version back.

 Your agent  (Claude Code · Codex · Gemini · Aider · opencode · Pi · …)
      │   tool output · logs · JSON · diffs · search results
      ▼
 ┌────────────────────────────────────────────────────┐
 │  caveman proxy   (your machine, your keys)          │
 │  detect() → json · log · code · diff · search · text│
 │  originals → local SQLite, recovery handle returned │
 └────────────────────────────────────────────────────┘
      │   smaller prompt, same answer
      ▼
 Your provider  (Anthropic · OpenAI · Google · Bedrock · Vertex · Azure · OpenRouter)

Whole team? One container. Same proxy in your VPC, one shared token, keys stay on server. Deploy it →

Months of your agent history already sit on your disk. caveman learn reads it, locally, read-only, no account, and ranks the places your tokens go, biggest first, with a one-line fix behind each. Then it keep watching, so you not have to remember.

Your agent re-sends its instructions (CLAUDE.md, skills, hooks) and the whole conversation with every message it sends the model. So a few hundred extra tokens in a setup file get paid again on every single message. That is what learn hunts.

caveman learn             # Claude Code + Codex + Gemini CLI + opencode; aider via CAVEMAN_AIDER_ROOT
caveman learn implement   # hand the fixes to Claude Code or Codex, one diff at a time, applied only on your yes

It run itself. Once caveman is on your agent (caveman claude, caveman codex, …), learn re-scans quietly after a session ends. Low priority, at most every 6 hours, never makes the session wait. When something new and heavy shows up, your next session opens with one line, one time:

caveman learn: new finding — Project CLAUDE.md is 423 lines (~9,699 tokens), loaded with every message (~9.7k tokens in every message, estimate). Run `caveman learn` to review.

Nothing new, nothing said. caveman learn autopilot off if you rather run it by hand.

It check your memory files. Claude Code loads only the first 200 lines (or 25KB) of MEMORY.md. Everything past that, your agent never sees, and nothing tells you. Learn tells you. It also catches @imports pointing at files that are gone, the same rule pasted into two files your agent loads (you pay for it twice, every message), file paths in CLAUDE.md that no longer exist, and memory notes the index forgot to link.

It say if you getting better. Week over week, from your own sessions, first run included. Real output from the maintainer's machine, bad news left in:

last 6 weeks  tokens per session   ▄▂▃▁█┊▄  +185% · worse
              peak context used    ▁▁▄▅█┊▁  +4 points · worse
              overloaded messages  ▁▂▃▇█┊▅  +2.9 points · worse
              week of Sep 21 (928 sessions) vs the 4 weeks before
              a trend is not a saving, and it does not show the cause

"Overloaded" means the conversation filled more than half of what the model can hold at once. Past that, answers tend to get worse (a common rule of thumb). Each week counts its middle session, not the average, so one giant session can't skew it. Weeks under 5 sessions say "not enough data" instead of guessing. The ┊ marks the week still running: shown, never compared.

It prove the fix, or undo it. implement re-measures after every change and undoes anything that didn't make each message smaller. Some fixes can't be re-counted, like a new skill that only pays off when it gets used. For those, caveman learn experiment runs it on for a stretch and off for a stretch over your own sessions, and gives no verdict before 5 sessions each way. Caveman never makes your agent dumber to make it cheaper.

Every verb, every check, every number it will and won't show: docs/technical/learn.md.

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` (needs `disable` first)
caveman toon encode|decode      # the TOON re-encoder, standalone
caveman stats                   # token history, API estimates, subscription equivalents

Caveman eating its own tail. Every skill you install is prompt text your agent reloads on every call. caveman convert renders the skill body to PNG pages in place, and the model reads it as an image. On the caveman skill itself: 1,069 to 415 estimated tokens, a 61% cut.

caveman convert --dry-run        # every installed skill, with the token math, no writes
caveman convert --agent claude   # convert the profitable ones
caveman convert --revert         # byte-identical restore from SKILL.orig.md

Convert only fires when pages beat the text. Any failure leaves the skill byte-identical and names the gate that said no.

caveman <agent> turns the proxy on for good and launches the agent. caveman wrap <agent> runs one session and leaves nothing behind. It never edits your config files.

In managed mode the Claude Code wrap also sends the repository (github.com owner/name) and current branch name as x-cave-tags, so Cloud can join a session's spend to the change it shipped. Branch names can carry a person's or customer's name. Not OK? Set CAVEMAN_WORK_TAGS=0 and no tags go. Or set your own x-cave-tags in ANTHROPIC_CUSTOM_HEADERS: the wrap sends yours exactly as written and adds nothing.

The proxy shrinks what a coding agent reads. The middleware does the same thing for the agent you are building, in the framework you already use. One wrapper around one call. Before each provider request it swaps big tool results for a shorter copy and hands the model a caveman_retrieve tool, so the model can read the original back whenever the short copy is not enough. Your conversation history keeps every original byte. Your provider, your client, your retries, your streaming: untouched.

TypeScript (Vercel AI SDK shown):

+import { createMiddlewareRuntime } from "@caveman-ai/sdk/middleware";
+import { withCaveman } from "@caveman-ai/middleware/ai-sdk";
+
+const runtime = createMiddlewareRuntime({ endpoint: "http://127.0.0.1:8787", mode: "compress" });
+const scope = { namespace: "support", session_id: conversationId, branch_id: "main", cache_epoch: "0" };
+
-const result = streamText(options);
+const result = streamText(withCaveman(options, { runtime, scope }));

Python (LangChain shown):

+from caveman_cloud.middleware import MiddlewareRuntime, Scope
+from caveman_middleware.langchain import with_caveman_agent
+
+runtime = MiddlewareRuntime(endpoint="http://127.0.0.1:8787", mode="compress")
+scope = Scope("support", conversation_id, "main", "0")
+
-agent = create_agent(model=model, tools=tools)
+agent = create_agent(**with_caveman_agent({"model": model, "tools": tools}, runtime=runtime, scope=scope))

The runtime is the same local proxy from the big rock, started once beside your app:

npm install -g @caveman-ai/cli && caveman setup --install
CAVEMAN_MODE=compress caveman start     # binds 127.0.0.1:8787; plain `caveman start` only records

Straight talk: a runtime left in record mode measures and changes nothing, whichever mode the client asks for, so set both. Decision reports say what was replaced and why, and carry no token counters; provider usage is the only savings number that counts. Runtime unreachable means your original request goes through untouched, unless you opt into strict mode.

Docs: middleware overview · Vercel AI SDK guide · Python guide · every framework and version · deploy beside your app · package READMEs for TypeScript and Python.

Rather not touch code? Point any SDK at the proxy with a baseURL swap instead: integrations/recipes/.

Good fit if you read your agent's answers more than you paste them somewhere, run long sessions full of logs and test output, or pay per token and want the reading side shrunk without changing your code.

Skip it if you are billed per request rather than per token (GitHub Copilot premium requests, for one: a shorter answer is the same request), or your workload is pure code generation with almost no prose to cut. The ruleset rides along as input tokens on every call (about 1,000 estimated for the full skill), and on terse one-liner Q&A that can cost more than it saves.

Measure it yourself. Run the same task with and without caveman and compare the provider's billing page. That A/B outranks every number on this page. If caveman loses on your workload, turn it off. Full list of where it loses: docs/HONEST-NUMBERS.md.

One idea everywhere: agent do more with less.

Frozen ones still install and work. Their best ideas moved in here.

Caveman make token small. Caveman Cloud make it provable. Local numbers are inferred, pinned benchmarks benchmark_counterfactual, neither is an invoice. Live traffic behind eval gates with signed receipts earns verified. That's Cloud. Waitlist at caveman.so

Your agent still talks to the provider you chose. The skill runs entirely on your machine, and nothing here needs an account.

The caveman CLI does send usage stats by default, and here's the honest why: caveman is free, one person maintains it, and those stats are how I find out which commands people actually use and which optimizations run in real workflows. That's what keeps this thing free and pointed in the right direction. Fair trade, we think.

What it sends: which commands ran, when your agent starts a session (the CLI's agent hooks send that one), token counts through and cut, a random install ID, your OS and CLI version, whether you're signed in, how you installed it, your timezone and language, and the IP address the stats come from. IPs get wiped after 90 days, everything else after 13 months. What it never sends: your prompts, your code, or your file paths. It tells you all this the first time you run it.

Not into it? One command and it's off forever, no hard feelings:

caveman telemetry off      # or set DO_NOT_TRACK=1

Want what it already sent gone too? telemetry off prints your install ID one last time. Send it to us and we delete it all. How: SECURITY.md.

Exact network, telemetry, and storage boundaries: SECURITY.md.

One license: Apache-2.0, whole repo, from Caveman 3.0.0 on. Skill, CLI, client SDKs, middleware, contracts, provider catalog, extension, and the full runtime: Engine, Proxy, Browse, MCP server, shrink, cavemem, shared Go platform. Read it, fork it, ship it, host it. Free like mammoth on open plain.

Releases before 3.0.0 keep the license they shipped with. Details in LICENSING.md.

engine/pixel embeds pxpipe (MIT) plus glyph atlases derived from Spleen 5×8 (BSD-2-Clause) and GNU Unifont (dual OFL-1.1 / GPLv2-with-font-exception); its NOTICE travels with that source.

"Caveman" and the rock logo are trademarks of Julius Brussee. "Powered by Caveman" is fine when true.

If caveman shows up in your paper, the way it showed up in Adobe's:

@software{brussee2026caveman,
  author = {Brussee, Julius},
  title  = {Caveman: why use many token when few do trick},
  year   = {2026},
  url    = {https://github.com/JuliusBrussee/caveman}
}

Caveman save you token, save you money. Star cost zero. Fair trade. ⭐