Caveman: token compression for Claude Code, Codex and other coding agents

The problem Caveman targets: tool output that eats your context window

Coding agents spend most of their budget on things the model did not ask for. A test run prints progress lines and stack traces. A search returns two hundred rows when three matter. A JSON response repeats the same keys a thousand times. Every one of those bytes is re-sent on the next provider call, so a single noisy command can shape the rest of a session.

Caveman attacks that from two directions. The original skill changes how the agent writes: answers get terse while code, commands and errors stay exact. The README frames the second product as the bigger change, quoting the tagline that the original skill made agents say less and Caveman 2 makes them read less too. The audience is anyone paying per token or hitting context limits with a terminal-based agent, which in practice means Claude Code, Codex, Gemini CLI and opencode users.

How the Caveman Engine classifies and compresses a payload

The proxy sits between your agent and the provider. No Caveman backend is involved: the proxy forwards each request to the provider you picked, and the recovery copies needed to reconstruct the original bytes stay on your disk. Claude Pro and Max OAuth credentials pass through to Anthropic as-is, according to the README.

The engine runs detect() on each payload, assigns it a type, then routes it to a compressor chosen for that type. The README's table is concrete about targets: json keeps keys, structure and error or message subtrees and collapses repetitive arrays, targeting 70 to 90 percent savings. log keeps errors, stack traces and first and last lines while dropping INFO and progress noise, targeting 85 to 95 percent. code keeps imports, signatures and types and elides function bodies, with syntax staying valid, targeting 40 to 70 percent. diff keeps file and hunk headers and changed lines. search-result keeps the top and bottom hits plus diagnostic and security hits. text and HTML keep headings and opening and closing context.

A second component, contextwindow.Pack(), fits candidate context into a token budget using BM25 relevance, recency and error signal, then returns the survivors in original order so chronology survives. That ordering detail matters more than it looks: a compressed transcript that loses sequence makes an agent misread cause and effect. The same engine is exposed as verbs (learn, explore install, shrink, browse, mem, trial) and as five MCP tools: caveman_compress, caveman_retrieve, caveman_stats, caveman_toon_encode and caveman_toon_decode.

Installing Caveman and running your first compressed session

The README presents two products and says to pick one or both. The first is the proxy, which shrinks what the agent reads. It installs globally through npm and then wires itself up. The caveman setup --install step is what registers the hooks and statusline.

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

Running caveman claude should launch Claude Code with provider traffic routed through the local proxy. The README states that in a pinned 54-run benchmark this path used 33.2% fewer provider-reported input tokens than direct Claude Code while passing all 18 exact-answer checks, and points to docs/WRAP-BENCHMARK.md for the method and limits.

The second product is the skill, which changes the agent's own output style. It is installed with the skills CLI and works across the 30+ agents the README lists.

npx skills add JuliusBrussee/caveman

There is also a full installer that wires Claude Code hooks and statusline and scans for every supported agent on the machine. It is documented as safe to rerun and requires Node.js 18 or newer.

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

Before changing anything, the cheapest first step is the read-only audit. caveman learn reads existing agent history on disk and scores the setup, with no account and no writes.

caveman learn             # Claude Code + Codex + Gemini CLI + opencode; aider via CAVEMAN_AIDER_ROOT

The report is documented as showing a Cave Score, token sinks ranked by flow with a one-line fix per row, how deep each session ran into its context window, a replay of what the fixes would have cut from past sessions, and a list-price illustration of the ranked sinks over 30 days. caveman learn implement then opens your own agent with the plan and the caveman-learn skill, which is instructed to propose each fix as a diff, apply only on your yes, re-measure, and revert anything that did not lower tokens per turn.

Where Caveman stops being the right tool

Byte-exact recovery is the design promise, and it is also the constraint. The proxy keeps recovery copies on local disk, so a compressed payload is only reversible while those copies exist. The README does not document a retention policy, a size cap or a cleanup command for that store, and it does not describe what happens when a retrieval handle is requested after the copy is gone. Anyone running this on a machine with a small disk or a shared CI runner is trusting an undocumented lifecycle.

The compression is also lossy by construction for the model's view of the payload, even when the original is recoverable for you. A log compressor that drops INFO lines is making a judgement about which lines never answer a question, and that judgement will occasionally be wrong in a debugging session where the interesting detail was a boring-looking line. The targets in the README's table are ranges, not guarantees.

Coverage is a second boundary. The verbs are documented for Claude Code, Codex, Gemini CLI and opencode, with aider reachable through the CAVEMAN_AIDER_ROOT environment variable. The README's own search data shows people asking about Copilot, Cursor and VS Code; the README does not document first-class support for those, so treat them as outside the documented path. If your team standardised on an agent that is not on the list, Caveman is not the tool for you yet.

Caveman versus a plain context-management habit

The obvious alternative is not another compression proxy. It is doing the work by hand: piping noisy commands through head, tail or grep, keeping a scratch file instead of pasting output into the chat, and starting a fresh session when the window fills. That approach costs nothing, installs nothing, and never mangles a payload.

It also fails in a specific way. It depends on you remembering to do it on every command, and it does nothing about the tool results the agent triggers on its own. Caveman's difference is that the compression happens inside the request path, after your agent has decided to run something, so it applies to output you never saw. The trade is control for coverage: you get less say over what was dropped, and in exchange the noisy paths you would have forgotten get handled. Caveman's own shrink verb shows the middle ground, since caveman shrink -- pnpm test compresses a single command's output with byte-exact recovery rather than routing the whole session.

Maintenance, licence split and upgrade cost

The repository is not archived and the last push was on 2026-08-23, the same day as the v2.3.1 release, so the project is current as of that date. The release history shows a tight cluster that day (v2.3.1, v2.3.0 and bin-v1.1.3 within ten minutes), which suggests small, frequent cuts rather than long release trains. The installer's package.json pins Node.js 18 or newer and pnpm 10.14.0 as the package manager, and the Go module declares go 1.26.5, so the toolchain is not conservative about language versions. Upgrading means tracking two version lines at once: the installer package is at 2.6.0 in package.json while the releases listed are 2.3.x, and the CLI dependency is declared as @caveman-ai/cli ^1.1.0.

Licensing is split and worth reading before deployment. The skill is MIT. The proxy runtime is BSL-1.1, and the repository carries separate LICENSE and LICENSE.BSL files plus a LICENSING.md. A source-available licence with a change date is not the same as MIT for commercial redistribution or for building a competing hosted service, so check LICENSING.md against how you intend to use it. This is a description of what the repository states, not legal advice.

Editorial conclusion

Adopt Caveman if you run Claude Code, Codex, Gemini CLI or opencode daily and your provider bill or context window is the binding constraint; the install is one npm command and the proxy keeps recovery copies on your own disk. Do not adopt it if your workflow depends on agents or providers outside the documented list, or if you need the compression path to be MIT rather than BSL-1.1. Verify first that caveman learn sees your history directories, that the 33.2% figure reproduces on your own sessions through caveman trial, and that your team is comfortable with the licence split between the skill and the proxy runtime.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes