One caveat right away, because it matters later: the project's documentation is not perfectly in sync. SECURITY.md, for instance, still calls 0.27.x the latest version while the releases and pyproject.toml show 0.35.0. In case of doubt, go by the release and the package metadata.

Where an agent actually burns context

In a long coding session a large part of the prompt is not the user's instructions at all but accumulated tool results: shell output, API responses, search results, tests, stack traces, repeated file reads and old calls.

Headroom works exactly at this point. According to the architecture documentation, system prompts and user intent are preserved, while compression targets bulk content blocks first of all.

Architecture: a pipeline, not one compressor

Every way of connecting leads into the same compression pipeline. In proxy mode Headroom intercepts the request, runs it through a set of transforms and sends it to the provider, returning the provider's answer to the client.

First comes CacheAligner - it watches the stability of the prefix cache and reports drift; per the current documentation it should not rewrite the user's prompt arbitrarily. Then ContentRouter determines the content type and hands it to a specific compressor. The heavy compressors and part of the type detection live in a native Rust extension. And CCR stores the original locally so the model can request the full fragment later.

An important property: the pipeline is designed to fail open. If a transform cannot handle a block safely, it returns the original content and does not break the request.

ContentRouter: first work out what this is

One algorithm is a poor fit for JSON, Python, build logs and prose all at once. So the content type is determined first - through pattern matching and, where available, Magika - and only then a specialised handler is chosen.

This is the strength of the approach. For JSON it matters more to keep the structure and the anomalous rows; for a stack trace, the errors and the call stack; for source code, the signatures and types. One rule cannot cover all of that.

SmartCrusher: the most convincing part

SmartCrusher is meant for large JSON arrays and structured tool results. And it does not simply cut the array after the first N elements - the selection weighs several factors at once: the first and last elements, errors and failure states, statistical anomalies, elements relevant to the current query, change points, and near-duplicates along with how informative the sample is.

There are safety limits too: per the documentation, arrays smaller than five elements and content under 200 tokens usually bypass SmartCrusher - there is nothing to compress there.

Logs and tool output

Build and test logs often consist of dozens or hundreds of repeated successful lines and a few genuinely important errors. Compression is least controversial here: if the task is to find the failure, the model does not need every passing step.

In the project's own benchmark a 200-line build log shrank from 2412 to 148 tokens - by 93.9%. That is the result of one specific test, not a promise for any log. And one more detail worth holding on to: the benchmarks page itself is stamped with version 0.5.18, meaning the figures were gathered long before the current release.

Plain text: here the numbers disagree

For prose and documentation there is a separate model-driven path - Kompress, built on ModernBERT and ONNX. And this is where the project's documentation contradicts itself.

The conclusion is simple: the project has no single number for plain text. The spread runs from 30 to 60 per cent, and the limitations page gives an even more modest 43-46 for documentation and articles. The real result depends on the content type, the handler chosen and the version, so the handsome figures from the JSON and log rows should not be carried across to prose. On top of that, the limitations page warns plainly that model-driven text compression adds latency and saves money rather than response time.

Code through a syntax tree: the capability exists, the default is cautious

There is a tree-sitter CodeCompressor in the package. The idea is clear: keep imports, classes, functions, signatures and types, and shorten the implementation bodies.

But the current limitations page stresses that in most real coding scenarios code passes through untouched. Recent code is protected, and if the user asks to analyse, review, fix or debug, the analysis context is protected too. The tradeoff is sensible: if the agent opened a function precisely to fix a bug, cutting out its body to save tokens is bad economy.

And there is something the documentation states more plainly than you might expect: code compression is disabled by default and opt-in. That wording appears in two places - the introduction page and the page on how compression works - and in the very same line as the 40-70% range. Which means the handsome figure applies to a mode you have to switch on yourself.

The discrepancy in numbers remains: different pages quote both 40-70% and 50-70% for code. Both apply when the compressor actually engaged and the safety gates allowed it, not to an ordinary session by default.

Telling, too, is that in the project's own benchmarks a Python source file compressed by exactly zero per cent - and that is marked as intentional behaviour rather than a failure.

CCR: compressed does not mean discarded

One of the most interesting parts is reversible compression. When a large tool result is compressed, the original is kept in a local hash-indexed store. The model gets the shortened version plus a marker, and calls a retrieval tool when it needs more.

Per the architecture documentation CCR is on by default in the relevant modes; there is a --no-ccr flag and marker-free paths. The approach is noticeably safer than discarding information for good: the prompt stays compact while the details can still be raised.

Saving tokens and the prompt cache are not the same thing

If every request rewrites the older part of the prompt slightly differently, the provider's prefix cache stops hitting. Locally it looks as though there are fewer tokens, while the real cost falls by less than expected.

That is why CacheAligner tracks volatile content and prefix drift, and the documentation separately stresses the value of a stable prefix for caching at Anthropic, OpenAI and Google. The practical point: count not "tokens before and after" but the net cost including cache reads and writes.

Four ways to connect it, and installation

The README lists wrappers for Claude, Codex, Grok, Copilot, Cursor, Aider, OpenCode, Cline, Continue, Goose, OpenHands, OpenClaw, Mistral Vibe, Oh My Pi and ZCode, while OpenAI-compatible clients can be pointed at the proxy.

For the command line the documentation recommends a separate environment:

Into a Python project it goes as a normal install, with the extras you need:

There is a package for Node.js too, with one caveat: the SDK sends content to a local proxy, so the proxy still has to be running separately.

And a container variant:

Claude Code, Codex and MCP

For coding agents Headroom positions itself as a transparent layer between the command line and the provider API:

Or the proxy is started by hand:

The README itself gives a figure of roughly 15-20% fewer tokens for this scenario - noticeably more modest than the 60-95% for JSON. That honest correction looks more plausible than carrying JSON benchmarks over to a real session wholesale.

There is a second route as well - hand compression to the agent through MCP. The server offers three tools: headroom_compress compresses a large block, headroom_retrieve pulls the original out of CCR, and headroom_stats shows the savings.

The difference from the proxy is fundamental: the proxy sits on the request path automatically, while MCP gives explicit tools the agent calls when it sees fit. For clients that do not inherit the PATH variable, the documentation advises spelling out the absolute path to the binary.

Beyond plain compression

By August 2026 the repository has gained features that belong to context engineering in general rather than to token compression specifically. There is cross-agent memory - a shared store for passing context between different agents with deduplication. There is SharedContext - compressed handover of large results from one agent to another with the option to fetch the original. There is headroom learn, which analyses failed sessions and can write corrections into the agent's instruction files. And mechanisms appeared for reducing not only input context but the verbosity of the model's answer.

All of it is interesting, but when choosing the tool it is worth answering the basic question first: does your workload actually suffer from large tool outputs. If not, the extra subsystems will not create meaningful savings on their own.

What the measurements show, and how to read the headline numbers

The project has a separate reproducible benchmark suite. One important detail: the published page states that the performance test ran on Apple M-series hardware and on version 0.5.18 - so the figures themselves are older than the current 0.35.0.

The last two rows are telling: code and search results pass through untouched. In a separate quality test the critical error was still found correctly when the input shrank from 10,144 to 1260 tokens, and all four verification questions were answered correctly. Latency measurements are published too: compression of large scenarios itself takes hundreds of milliseconds or seconds, but thanks to less prefill on the model's side the authors got a positive balance in 11 scenarios out of 12.

Now about the figures that reach the headlines, and how far they can be trusted.

60-95% on JSON - supported by the direction of the benchmarks: 83-91% is published for large arrays, and structured logs go above 90%.

15-20% for coding agents - a README claim. This is already an end-to-end figure rather than a measurement of one compressor, and the real percentage depends on the share of machine output against code and user prompts.

"The same answers" - too broad a formulation. The project shows specific accuracy tests, but no lossy compression scheme can guarantee identical quality on every unknown task.

Compression for RAG - the documentation disagrees with itself: the introduction speaks of RAG results as a goal, while the limitations page lists RAG documents as passthrough.

40-70% on code - only with tree compression actually active. The default safety gates often leave code untouched.

Limitations and security

Short conversations barely gain: the limitations page cites a median of about 4.8% for short exchanges. On a single question with no tools Headroom simply has nothing to work with.

Code is protected exactly when it is needed - during debugging, review and fixes. That lowers the savings but protects correctness, and for a coding agent it is a plus rather than a flaw.

Compression can add latency, especially model-driven text compression. The gain is counted across the whole chain, not inside the compressor.

Not everything compresses: short content, malformed JSON, small arrays, system prompts and already-compact blocks pass through as they are.

And separately - parts of the documentation contradict one another. The ranges for text, the behaviour with RAG and code compression are described differently on different pages. The project moves fast, so for production it is worth pinning a specific version and testing on your own workload.

On security the picture is this. Headroom positions itself as local-first: in proxy mode the content is processed on your machine and then goes to the provider you were addressing anyway; the CCR store is local too. But the proxy stands at an extremely sensitive point - prompts, tool results, credentials in headers and potentially private code all pass through it. So treat it as part of your trusted computing base: install from the official repository, do not expose it publicly without need, control the CCR storage, read the release notes before upgrading, and pin the version instead of blindly taking the latest.

There is an argument for that caution in the project's own history: among the fixes in 0.34.0 are security-related dependency bumps for aiohttp and cryptography, and neighbouring releases changed CORS and transport behaviour. And once more about the desync: the security policy in the repository still lists 0.27.x as the supported latest, so go by the releases.

Headroom versus pxpipe: one goal, entirely different mechanics

These are not the same tool in different languages. Headroom tries to understand the data; pxpipe tries to change the economics of representing it.

When it makes sense, and the verdict

A very good candidate is large JSON tools: this is where SmartCrusher meets the project's greatest strength. A good one is continuous integration, tests and logs, with plenty of repetition and few genuinely significant lines. A good one is long agent sessions that pile up dozens of tool results. A weak one is ordinary chat, where there is little bulk content and nothing safe to discard. A limited one is pure work with code, because the safety gates deliberately protect exactly that. And precise machine data must be tested: CCR lowers the risk, but automatic sampling still changes what the model sees right now.

Headroom is interesting not for promising another 90% in savings but for tackling the problem as engineering: different compressors for different content types, caution around critical code, separate logic for the provider's cache, and reversible retrieval for what was removed.

The most convincing area today is large structured tool outputs, JSON and noisy logs. There the redundancy is obvious, the local benchmarks are decent, and there is minimal reason to make the model read every line. For Claude Code and Codex the real savings will be far more modest than the headline figures - the README itself now says 15-20%, and that is an honest correction: in a normal session a significant part of the useful context is code and fresh tool results, which Headroom deliberately does not cut aggressively.

Think of it not as a magic prompt shrinker but as a local context-engineering layer. It is especially useful where the agent is drowning not in knowledge but in machine noise.

Sources

The material was checked on 13 August 2026 against the project's primary sources. Figures from the benchmarks are marked in the text as the project's own test results. The method was this: where the README, the documentation and the package metadata disagreed, priority went to the current GitHub release and pyproject.toml, while contradictions in behavioural claims were not hidden but listed separately. Supplemented on 15 August 2026 against a fresh clone: the plain-text discrepancy table rebuilt from the actual documentation pages, the fact that code compression is disabled by default added, the version the benchmarks were gathered on noted, and the star count updated.

• GitHub - headroomlabs-ai/headroom
• Releases - v0.35.0
• pyproject.toml - version, licence, dependencies
• LICENSE - Apache-2.0
• SECURITY.md
• Documentation - Introduction
• Architecture
• How Compression Works
• SmartCrusher
• Limitations
• Benchmarks
• Installation
• Reversible Compression (CCR)
• SharedContext