---
title: "Caveman vs Headroom for recoverable context compression"
description: "Caveman and Headroom both compress agent context and let the agent retrieve original content later. Caveman pairs that recovery path with local coding-agent setup and a store that retains existing ori"
canonical: https://caveman.so/compare/headroom
last-updated: 2026-09-07
---

# Caveman vs Headroom for recoverable context compression

Caveman and Headroom both compress agent context and let the agent retrieve original content later. Caveman pairs that recovery path with local coding-agent setup and a store that retains existing originals when it reaches capacity.

Choose Caveman when you want a local coding-agent path with content-specific compression, explicit pass-through behavior, and originals that remain available when the store reaches its budget. Test Headroom too if its library or existing integrations fit your application.

## The closest comparison

| Area | Caveman | Headroom |
| --- | --- | --- |
| Entry points | CLI, local proxy, compression engine and MCP recovery | Library, proxy, agent wrap and MCP tools |
| Original content | Local content-addressed store before publishing a lossy view | Local compression store with retrieval tools |
| Store at capacity | New lossy transforms pass through; existing handles are retained | Documentation describes LRU-style eviction |
| Agent recovery | Native recovery tooling or supported proxy-side handling | Recovery tooling and protocol-specific proxy handling |
| Decision evidence | Published paired task benchmark and local inferred reports | Published methods and per-content measurements to examine on your workload |

Headroom's [recovery documentation](https://docs.headroomlabs.ai/docs/ccr) describes a persistent SQLite backend in its proxy. Compare retention at capacity as well as persistence across restarts. Test streaming and tool calls on the protocol you plan to use.

## What the published benchmark says

Our [CaveBench Wrap report](https://github.com/JuliusBrussee/caveman/blob/main/docs/WRAP-BENCHMARK.md) ran six fixed tool-output tasks three times per arm, using Claude Code 2.1.223 with Sonnet 5.

| Arm | Exact answers | Input reduction at held quality |
| --- | --- | --- |
| Direct Claude Code | 18 / 18 | Baseline |
| Caveman wrap plus skill | 18 / 18 | 33.2% |
| Headroom wrap | 15 / 18 | 6.7% |

These controlled results use a `benchmark_counterfactual` basis rather than customer billing data. Headroom failed three YAML cases, which are excluded from its matched reduction figure; Caveman's HTML case used 9.9% more input than direct. The report includes uncertainty intervals, pinned configurations, and the per-case results.

This gives you a reason to try Caveman first on similar tool-heavy work. It does not establish that Caveman wins every document, harness, or model combination.

## Why storage behavior matters

A smaller view can be enough for the current answer and insufficient for the next question. Suppose an agent receives a summary of a deployment configuration, then needs an omitted value ten turns later. Its recovery handle is part of the conversation's state.

Caveman keeps existing originals when its local storage budget is reached. The tradeoff is deliberate: future requests may pass through at full size. A long-running agent gets a predictable failure mode instead of silently losing earlier recovery data.

Still test a process restart, a missing handle, and a full store. Recovery promises should be checked against the system you run, including its permissions and storage volume.

## Avoid double compression during evaluation

Do not put both wrappers around the same session for your first comparison. One may transform the other's marker or reduce the context before the second tool sees it. That measures a stack you did not intend to compare.

Use a direct baseline and separate fresh sessions for each candidate. Keep skill instructions consistent, or record them as part of the candidate. Include recovery calls and their follow-up model requests in total usage.

## Move one workflow first

The [Headroom switching guide](/switch/headroom) covers wrapper replacement, port conflicts, preserving old recovery data, and a reversible rollout. For library users, start with a recorded payload before changing an application's compression call.

Sources: [Headroom project](https://github.com/headroomlabs-ai/headroom), [Headroom recovery contract](https://docs.headroomlabs.ai/docs/ccr), and [Caveman recoverable compression](https://docs.caveman.so/docs/proxy/recoverable).