headroom
worthwhileAggressive context compression with reversible caching that vanilla Claude cannot self-implement—real token savings without answer degradation.
What it is
A local proxy/library/MCP server that compresses prompts, tool outputs, logs, and RAG chunks before they reach an LLM. Uses content-type-specific compressors (JSON crusher, AST-based code compressor, a small fine-tuned transformer for prose) and caches originals for reversible retrieval. Runs entirely on-device.
How it differs from vanilla Claude
Claude will not compress its own input. A vanilla agent cannot apply AST-aware code compression, detect JSON structure to drop keys/empty arrays, or stabilize prefix text to maximize KV-cache reuse. Headroom interposes transparently via proxy or wrap, reducing tokens 60-95% on structured data while answering identically. The reversible cache means the model can fetch full original when needed—vanilla Claude has no such mechanism.
Skill, plugin, or workflow shift?
Workflow-shift because it changes the fundamental cost model of every prompt: you install one binary, wrap your agent, and from then on all context entering the model is compressed. Not a plugin you toggle; it rewrites the data pipeline. The MCP server and library modes let it be composed into custom pipelines, but the primary value is the always-on compression layer.
Devil's advocate — is this just complexity?
Claude's 200k context window already fits most tool outputs. The 60-95% savings claim is worst-case—real code agents average 15-20%. The custom Kompress-v2-base model (only on HF, 4-bit) adds a quality risk when it hallucinates on compressed prose. For most users, the proxy dependency, KV-cache alignment complexity, and output estimation tools are premature optimization: you save tokens by writing better prompts. The 'reversible' CCR cache is elegant but adds a retrieval call that can fail or be ignored by the model, making answers nondeterministic. This is a prompt in a compression glove, not a new capability.
What would make it better
1) Default-on with zero config—install and wrap should require no env vars. 2) Drop the custom model dependency; use only structural compressors (JSON, AST) that are provably lossless. 3) Proxy should auto-detect and serve the wrapped agent without manual port binding. 4) Output token reduction should be on by default with a per-request control group toggle. 5) Provide a headroom unplug one-liner that fully restores original agent config.
The honest case for it
If you pay per token (API costs) or have latency constraints (many tool calls per turn), Headroom saves real money and time. The reversible cache is not a gimmick—it lets you aggressively compress without losing fidelity, and models can and do call headroom_retrieve when they need details. The wrap mode is one command, the accuracy benchmarks hold, and you can verify savings yourself with headroom perf. For a team running 100k+ agent turns a day, this pays for itself in a week.
Who it's for
Audience fit
Depth and leverage for a technical engineer who wants to understand it and level up their workflow — not just offload work.
Value for someone who wants a more capable tool without the technical depth — accessible, does-it-for-you.
Empowers engineers trimming token budgets in agent pipelines; vibe coders benefit from wrap-and-forget but lose reversibility nuance.