Caveman vs Headroom: context compression compared

Headroom is the closest thing Caveman has to a twin. Both detect what kind of content an agent is reading, compress each kind with its own compressor, store the original locally and give the model a tool to fetch it back. Headroom covers more ground: a library, a proxy, a one-command wrapper for sixteen coding agents, an MCP server, shared memory and output shaping, all under Apache 2.0. Caveman is narrower. Its middleware runs inside the framework you already use, keeps inference on your provider client, and its store never evicts an original. The right pick depends on where you need recovery to work and for how long.

What is Headroom?

Headroom is an open source context compression layer for AI agents, developed at headroomlabs-ai/headroom (the old chopratejas/headroom URL redirects there). It is written in Python with a Rust core, ships a TypeScript SDK on npm, and is licensed Apache 2.0. On 30 September 2026 the repo had about 74,000 stars, and v0.39.1 shipped on 26 September.

A ContentRouter picks a compressor per content type: SmartCrusher for JSON, an AST-aware CodeCompressor for eleven languages, and Kompress-v2-base, Headroom's own model trained on agent traces, for prose. CCR (compress, cache, retrieve) stores originals and injects a headroom_retrieve tool. A live-zone rule compresses only new bytes, so the cached prompt prefix stays identical.

You can run it four ways:

pip install "headroom-ai[all]"
headroom wrap claude              # wrap a coding agent
headroom proxy --port 8787        # OpenAI-compatible proxy, no code changes
headroom mcp install              # MCP tools for any MCP client
# or in code: from headroom import compress

Beyond compression it offers cross-agent memory, headroom learn (mines failed sessions and writes corrections to CLAUDE.md or AGENTS.md), optional output token reduction, and image compression. Framework hooks cover the OpenAI and Anthropic SDKs, the Vercel AI SDK, LiteLLM, LangChain, Agno, Strands and ASGI apps. For teams, Headroom Labs offers supported self-hosted or fully managed deployments by contact.

Headroom's own published numbers: 21% to 57% fewer tokens across four scenarios built from MCP output, over 90% on repeated JSON arrays and logs, little on prose, and 0.21 ms p50 compression latency on a 10K-token JSON result.

How does Caveman work?

Caveman Middleware adds a native adapter to your framework: LangChain and LangGraph, LlamaIndex, Pydantic AI, CrewAI, AutoGen, Mastra, the Vercel AI SDK, the OpenAI, Anthropic and Google clients, LiteLLM, MCP and more. Before each provider call it takes a copy of the request, sends eligible tool results to a local runtime, swaps each for a shorter view and registers caveman_retrieve through the framework's own tool mechanism. Your application history stays byte for byte as you built it, and the provider call still goes out through your client.

Detection and compression are deterministic Go code with no model call. The runtime recognises JSON, logs, diffs, code, tables, search results, terminal output, config, HTML and plain text. Originals are written to the store before any lossy replacement. If the write fails, nothing gets shortened.

For coding agents there is Caveman Proxy: caveman claude points Claude Code at a local proxy and installs recovery for that host.

Headroom vs Caveman: feature comparison

Where does recovery actually work?

This is the first real difference. Headroom's CCR docs say the full loop (inject headroom_retrieve, catch the model's retrieval call, resolve it) lives in the proxy's request handlers. The direct Python SDK client still stores originals and embeds markers, but you resolve those markers yourself. Their TypeScript compress() has an option to inject the tool.

Caveman Middleware wires recovery into each framework's tool loop. In LangChain the agent sees caveman_retrieve as one more tool and calls it like any other. Inference never passes through a proxy.

If a local proxy in front of inference is fine, Headroom's approach is simple and works from any language. If it is not, Caveman's adapters avoid one.

How long do originals stay recoverable?

Headroom's proxy keeps CCR originals in a SQLite file that survives restarts, with a default TTL of 1,800 seconds and LRU eviction when the store fills. Its docs recommend raising HEADROOM_CCR_TTL_SECONDS for long autonomous runs, and that is good advice.

Caveman's proxy store evicts nothing. Middleware handles are grants that stay valid for 24 hours after the last call that touched them.

Picture an agent that reads a 30,000-line Terraform plan at 09:00 and needs one subnet ID from it at 10:20. With Headroom's default TTL that entry has expired and the agent reruns the plan. With a higher TTL, both tools answer with one recovery call.

Is there a benchmark?

Our CaveBench Wrap report (6 August 2026) ran six fixed tool-output tasks three times each on Claude Code 2.1.223 with Sonnet 5 and Headroom 0.33.0. Caveman, with its output skill loaded, passed 18 of 18 exact-answer checks with 33.2% fewer provider-reported input tokens than direct. Headroom passed 15 of 18, missing three YAML runs, and saved 6.7% on the pairs it passed. Caveman's HTML case used 9.9% more input than direct.

Read it with care. We built the benchmark and chose the tasks, and Headroom has shipped six minor releases since 0.33.0. The configs are pinned, so rerun it against the current version.

When should you use Headroom?

Use Headroom if you want one tool that does a lot: proxy, library, MCP, shared memory across agents and output shaping. It is the better fit when your coding agent is on its wrap list and not Caveman's (Cline, Continue, Goose, OpenHands or Copilot CLI, for example). It also wins if you need an Apache 2.0 license all the way down, if you are on Python 3.10 to 3.12, or if you want a managed team deployment today.

When is Caveman the better pick?

Pick Caveman when recovery has to work inside your framework's own agent loop without a proxy in front of inference. It also suits agents that run for hours and must still read something from the start, since the store never expires an original. And it fits teams that want no model downloads: Headroom's prose model and some detection features fetch ONNX Runtime and Hugging Face assets, while Caveman's transforms are plain code. Caveman also ships adapters for Mastra, CrewAI, AutoGen, Pydantic AI and LlamaIndex, which are not in Headroom's README integration table.

Can you run Headroom and Caveman together?

Not on the same session. Both rewrite tool results and both inject a retrieval tool, so one can compress the other's markers. Both also default to port 8787. Run them in separate sessions and compare, which is what the switching guide walks through.

FAQ

Is Headroom open source? Yes. The whole repo is Apache 2.0, and the managed team offering sits on top of it.

Which one saves more tokens? It depends on your payloads. Both do best on repetitive JSON and logs and little on dense prose. Measure your own tasks with the cost guide.

Does either send my data to a server to compress it? No. Both compress locally. Headroom's anonymous telemetry beacon is on by default and turns off with HEADROOM_BEACON=off.

Sources

• Headroom on GitHub
• Headroom CCR docs
• Headroom limitations
• Caveman Middleware docs
• Caveman recoverable compression
• CaveBench Wrap report