Caveman Cuts Claude Code Token Usage by 33% Using Caveman-Speak

The first version, "Caveman 1," was a skill that changed how the agent phrases its answers. A long-winded explanation like "The React component re-renders because a new object reference is created on every render. I'd recommend wrapping it with useMemo" gets compressed into something like "New object ref every render. Wrap with useMemo" — while code, commands, and error messages stay untouched, only the prose gets shortened. But this approach only cut the tokens the agent "speaks." It did nothing about the tokens the agent "reads" every turn — tool schemas, files, logs, conversation history — which pass through unchanged.

The newly released "Caveman 2" and its local proxy fill that gap. Before the agent sends a request to the model provider, the proxy compresses the content first, and restores the original byte-for-byte when needed. In a fixed 54-run Claude Code benchmark disclosed by the developer, the proxy reduced provider-reported input tokens by 33.2% compared to direct calls, while passing all 18 correctness checks.

The Trick of Turning Text Into Images

One of the proxy's core ideas is exploiting a gap in how billing works. Text is priced by the token, but images are calculated differently. So the proxy takes dense blocks of text — compressed JSON tool lists, long logs, old conversation history — and renders them as PNG images to send instead. In one disclosed real-world example, 8,622 characters of text became a single 1568×232-pixel PNG, shrinking roughly 2,597 text tokens down to 534 image tokens. However, the developer notes this only pays off for dense, long-line content; for code made up of short lines it actually backfires, so it gets filtered out automatically.

"caveman convert" applies the same principle to the skill files themselves. It turns the body text of installed skill files into PNG pages so the model reads them as images. Measured on the Caveman skill itself, this cut an estimated 1,069 tokens down to about 415 tokens — roughly a 61% reduction.

Browser Automation and MCP Tools

Caveman exposes five tools through an MCP (Model Context Protocol) server — caveman_compress, caveman_retrieve, caveman_stats, caveman_toon_encode, and caveman_toon_decode. Its browser automation feature, which runs in environments with Chrome installed, reportedly used just 121 tokens for a query against a 200-row operations table, compared to 15,704 tokens for the same task using Playwright's ARIA-based approach. That said, the developer admits that for simple tasks with few elements, like a checkout form, Caveman can actually end up using more tokens, since it returns action UIDs alongside restoration handles.

The Catch Behind the "Honest" 65% Figure

The developer clearly made an effort to explain the 65% reduction figure without overstating it. The skill only reduces output tokens — input and reasoning tokens stay the same — and the skill itself adds roughly 1,000 to 1,500 tokens of overhead per turn. In workflows already tuned to answer briefly, net savings could turn negative, the developer noted. The repository description carries the line "Caveman never makes your agent dumber to make it cheaper."

How to Try It

Caveman is described as working across more than 30 agents, including Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, and Copilot. There are broadly two ways to use it.

1. To use only the skill, install it and, if the agent doesn't activate automatically, run the /caveman command. Adjust intensity with /caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra, and turn it off with /caveman off or by switching back to normal mode.
2. To also cut input tokens, wrap the agent with the local proxy using the caveman <agent> command. For frameworks not listed in the repository — such as Vercel AI SDK, LangChain, LiteLLM, OpenAI Agents, CrewAI, or PydanticAI — you can connect by simply pointing the baseURL to the proxy address.

To analyze past agent usage logs stored on disk, run caveman learn. It runs locally in read-only mode, works without an account, and shows a "Cave Score" report ranking where tokens are being wasted. Fixes that have actually been applied can be logged with caveman learn applied <sink_id>, and the next run will report whether things improved, stayed the same, or got worse. Telemetry is on by default and can be disabled with caveman telemetry off or the environment variable DO_NOT_TRACK=1.

Open Source, but With a Split License

The core skill, CLI, and TS/Python SDKs are freely available under the MIT license. However, the core runtime that handles actual computation — the compression engine, proxy, cache engine, browser automation, and MCP server — is distributed under BSL-1.1. It can be used free of charge for a company's own traffic, including commercial services, but offering it to third parties as a hosted or managed service requires a commercial license. The BSL-licensed code is set to automatically convert to Apache 2.0 on June 21, 2030, or four years after each version's initial release, whichever comes first.

Benchmarks at a Glance

Segment	Reduction	Notes
Proxy input tokens (54-run benchmark)	33.2%	Passed all 18 correctness checks
Skill output tokens (original Caveman)	Up to 65%	Part achievable via a "be concise" instruction alone
Browser 200-row table query	129.8x	Compared to Playwright's ARIA-based approach
Skill body converted to image	~61%	Estimated 1,069 → 415 tokens

Editor's Take

What makes this project interesting isn't the token savings themselves, but the willingness not to hide how those savings are achieved. Most AI tools lead with headline numbers like "X times faster" or "cuts costs by X%," burying the caveats in footnotes. Caveman does the opposite — it puts the eye-catching 65% figure front and center, while openly admitting in its own repository description that roughly half of that number could come from a single prompt line telling the model to "be concise." That kind of honesty is rare.

From a practical standpoint, the target audience for this tool is clear. Teams that run agentic coding tools all day tend to underestimate how much input-token cost piles up from tool schemas, full file contents, and logs being resent every turn. The warning that skill overhead alone could cause net losses in setups already tuned to answer briefly should also be taken seriously. The pixel-compression trick — turning text into images to exploit a gap in billing structures — could push model providers to reconsider how they price text versus image tokens. It remains to be seen whether Anthropic or OpenAI will issue an official stance on this kind of workaround compression in the coming weeks, or simply leave it alone. Those who want to try it themselves can sign up in advance on the waitlist page.