# 02 — Headroom v0.34.0: current design (https://jackin.tailrocks.com/research/context/tools/02-headroom-design/)



## Summary [#summary]

Headroom offers the broadest reversible input-compression pipeline in the compared set, but its trained hot-path compressor and proxy boundary require independent quality and reliability proof.
Cutoff: **2026-08-12**. Current stable: [v0.34.0](https://github.com/headroomlabs-ai/headroom/releases/tag/v0.34.0), released 2026-08-05.

Headroom is the most mature **broad input-compression pipeline** in the named set. It routes each payload to a content-specific compressor, uses a trained model for selected text, stores recoverable originals, and can operate as a library, MCP server, wrapper, or provider-facing proxy. Current Headroom also has opt-in output-verbosity and effort controls, so it is no longer input-only in feature scope.

## Question and scope [#question-and-scope]

How does Headroom v0.34.0 compress and recover context, and where do its model and proxy boundaries add risk?

## Method [#method]

The review fixes Headroom to v0.34.0, traces each compression and recovery boundary through upstream documentation and source, and separates mechanism evidence from accepted-task outcomes.

## Findings [#findings]

### Current facts [#current-facts]

| Field             | Current value                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------- |
| Repository        | [headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom)                   |
| Stable release    | [v0.34.0](https://github.com/headroomlabs-ai/headroom/releases/tag/v0.34.0)               |
| Adoption snapshot | 65,972 stars / 193 subscribers / 5,038 forks / 621 open issues and PRs                    |
| Core identity     | Content router + typed compressors + Kompress text model + CCR recovery                   |
| Deployment        | Python/TypeScript APIs, MCP, local proxy, agent wrappers, Docker                          |
| Current headline  | 60–95% fewer tokens on targeted payloads; not stated here as an end-to-end task guarantee |
| License           | Apache-2.0                                                                                |

Metadata source: [GitHub API](https://api.github.com/repos/headroomlabs-ai/headroom). Current architecture and setup: [repository README](https://github.com/headroomlabs-ai/headroom).

### Current pipeline [#current-pipeline]

```text
request or tool payload
       ↓
content classification
       ↓
JSON / logs / search / source / HTML / tables / prose / history
       ↓
typed deterministic compressor or Kompress model
       ↓
shorter-output and policy checks
       ↓
compressed payload + CCR reference to exact original
       ↓
provider or agent context
```

The design advantage is specialization. JSON arrays can be typed and sampled; logs can preserve anomalies/errors; source can expose structure; search results can be normalized; free-form text can use Kompress. One generic summary transform would lose the guarantees each content type needs.

CCR makes lossy compression operationally recoverable. “Recoverable” does not mean the active model saw every omitted detail; it means the agent can request the original when uncertainty or an exact task demands it.

### What v0.34.0 currently provides [#what-v0340-currently-provides]

* PHP code compression and expanded IDE/agent wrapper support.
* A marker-free lossless provider seam through `/v1/compress`.
* Frozen-message handling and cache/accounting corrections.
* Kompress-v2 checkpoint merging and runtime/prefetch fixes.
* Anonymous compression telemetry that states prompts and payload content are excluded.
* Optional verbosity steering and effort routing for output-side reduction.
* Serena installed by the wrapper's current default unless disabled.
* RTK and lean-ctx CLI context tools removed from the bundled wrapper path.

Release source: [v0.34.0 notes](https://github.com/headroomlabs-ai/headroom/releases/tag/v0.34.0).

### Current evidence [#current-evidence]

The current repository supplies per-payload benchmarks, telemetry machinery, holdout concepts, and compression counters. These are first-party. No independent end-to-end benchmark explicitly testing **v0.34.0** was found at the cutoff, so older-version results are not projected onto this release.

The current Caveman v2 first-party [wrap benchmark](https://github.com/JuliusBrussee/caveman/blob/v2.0.0/docs/WRAP-BENCHMARK.md) includes a Headroom arm, but it is a competitor-owned six-fixture test and cannot establish general Headroom performance.

## Implications for jackin❯ [#implications-for-jackin]

### Benefits [#benefits]

* Broadest mature input reach: structured payloads, logs, source, RAG, history, and provider requests.
* Content-aware transforms instead of blanket truncation.
* Exact-original recovery through CCR.
* Lossless provider seam for callers that cannot accept lossy markers.
* Multiple deployment forms; can be tested without committing to a global wrapper.
* Apache-2.0 across the repository.
* Current output/effort controls can reduce separate token classes under one policy layer.

### Best fit [#best-fit]

Test Headroom when large JSON, logs, RAG chunks, mixed tool results, or long request history dominate avoidable fresh input and exact recovery is required. Start with the narrowest deployment—library or MCP on selected payloads—before a whole-agent proxy/wrapper.

Avoid a global install when native retrieval already selects small precise slices, latency is critical, or policy forbids local models, telemetry, user-scope config changes, or request interception.

### Current verdict [#current-verdict]

Headroom v0.34.0 is the best current **broad reversible compressor** in this set. Its 60–95% headline is plausible for selected compressible payloads but unproven as a latest-release accepted-task result. Status: **strong architecture, mature feature set, verify net benefit locally**.

Next: [03 — RTK v0.45.0](/research/context/tools/03-rtk-design/).

## Limitations and unknowns [#limitations-and-unknowns]

### Costs and risks [#costs-and-risks]

* Larger process and dependency surface than RTK: Python/Rust components, optional model artifacts, proxy/MCP state, and wrapper configuration.
* A proxy sees full requests and can affect caching, auth, streaming, and provider compatibility.
* Kompress adds model/runtime latency and a model supply-chain surface.
* Wrapper defaults may install or configure adjacent tools such as Serena at user scope; inspect and disable unwanted writes.
* Anonymous telemetry is current behavior; privacy review must use current code/config, not an assumption of zero egress.
* Reversible omission can still cause extra retrieval turns or wrong reasoning before recovery.
* Current `SECURITY.md` identifies an older release as latest; release metadata and code are more current than that document.

## Sources [#sources]

Evidence and repository references are cited inline beside the claims they support.

## Related work [#related-work]

* [Token-optimization tools dossier](/research/context/tools/)
* [Token-optimization techniques](/research/context/techniques/)
* [Context engine](/research/context/engine/)