Headroom Compresses Agent Context by 60–95% With No Accuracy Loss
AI agents burn tokens on context that does not need to be there. Tool outputs dump 10K tokens of JSON when the LLM only needs the error at position 67. Build logs pipe 2,400 tokens of output when the agent just wants the single line that says BUILD FAILED. RAG results return 100 documents when 15 would produce the same answer.
Headroom is a new open-source context compression layer that sits between your agent and the LLM provider. It compresses everything the agent reads - tool outputs, logs, RAG chunks, files, conversation history - before it reaches the model. The project crossed 17,500 GitHub stars in its first week.
How it works
Headroom runs locally. Messages pass through a pipeline of six compression stages before reaching the model:
CacheAligner extracts dynamic content (dates, UUIDs, session tokens) from the system prompt and moves it to the end. This stabilizes the prompt prefix so provider KV caches hit instead of missing on repeated calls.
ContentRouter inspects each piece of content and routes it to the right compressor. JSON arrays go to SmartCrusher. Source code goes to CodeCompressor. Prose and logs go to Kompress-base, a custom HuggingFace model trained on agentic traces.
SmartCrusher handles JSON - the most common high-token offender in agent workflows. It runs field-level statistical analysis, selects a representative subset using the Kneedle algorithm on bigram coverage, and factors out constant fields. It preserves errors, anomalies, and distribution boundaries unconditionally. The algorithm retains 30% of items from the array start (schema), 15% from the end (recency), and 55% by importance score.
CodeCompressor applies AST-aware compression for Python, JavaScript, Go, Rust, Java, and C++. It preserves function signatures and control flow while stripping implementation details irrelevant to the current task.
Kompress-base handles freeform text - prose, logs, documentation - using a model trained specifically on agent conversation traces.
CCR (Compress-Cache-Retrieve) makes the entire pipeline reversible. Every time SmartCrusher compresses content, the original is stored in a local LRU cache with a hash key. The compressed output includes a marker like [1000 items compressed to 20. Retrieve more: hash=abc123]. If the LLM needs the full data, it calls the headroom_retrieve tool, which returns the original content in under 1 millisecond. This eliminates the traditional trade-off between aggressive compression and data loss.
Real workloads
Headroom ships with performance measurements on realistic agent workloads, not synthetic benchmarks:
| Workload | Before (tokens) | After (tokens) | Savings |
|---|---|---|---|
| Code search (100 results) | 17,765 | 1,408 | 92.1% |
| SRE incident debugging | 65,694 | 5,118 | 92.2% |
| GitHub issue triage | 54,174 | 14,761 | 72.7% |
| Codebase exploration | 78,502 | 41,254 | 47.4% |
The tool is selective about what it compresses. Already-compact formats like grep output and source code pass through unchanged - SmartCrusher only targets JSON arrays, shell output, and build logs, where the token bloat lives. Content-type breakdowns show the pattern:
| Content type | Original tokens | Compressed | Saved |
|---|---|---|---|
| JSON array (100 items) | 3,163 | 297 | 90.6% |
| JSON array (500 items) | 9,526 | 1,614 | 83.1% |
| Shell output (200 lines) | 3,238 | 469 | 85.5% |
| Build log (200 lines) | 2,412 | 148 | 93.9% |
| grep results (150 hits) | 2,624 | 2,624 | 0.0% |
| Python source (~480 lines) | 2,958 | 2,958 | 0.0% |
The 0% compression on grep and Python source is deliberate. These formats are already compact. The code compressor passes them through to preserve correctness.
Accuracy does not degrade
Compressing context is only useful if the LLM can still answer correctly. Headroom tests accuracy on standard benchmarks with and without compression:
| Benchmark | Category | Baseline | Headroom | Delta |
|---|---|---|---|---|
| GSM8K | Math reasoning | 0.870 | 0.870 | ±0.000 |
| TruthfulQA | Factual accuracy | 0.530 | 0.560 | +0.030 |
| SQuAD v2 | Question answering | - | 97% | at 19% compression |
| BFCL | Tool calling | - | 97% | at 32% compression |
GSM8K math reasoning scores are identical with and without compression. TruthfulQA edges up slightly, likely because removing noise lets the model focus on the facts. SQuAD v2 and BFCL maintain 97% accuracy at 19% and 32% compression respectively.
A specific test with 100 production log entries, where the critical error was at position 67, demonstrates this in practice: 10,144 tokens compressed to 1,260 (87.6% reduction), and the LLM correctly answered all four questions about the error, error code, resolution, and affected count.
Deployment modes
Headroom offers three ways to integrate, all feeding into the same compression pipeline:
Library mode - import and wrap your client. Two lines in Python: from headroom import compress; compress(messages). TypeScript: await compress(messages, { model }). Works with any codebase.
Proxy mode - zero code changes. Run headroom proxy --port 8787 and point your agent at http://localhost:8787 instead of the provider directly. Any OpenAI-compatible client works.
MCP server mode - headroom mcp install registers headroom_compress, headroom_retrieve, and headroom_stats as MCP tools for any MCP-native client.
Agent-specific wrappers also exist: headroom wrap claude, headroom wrap codex, headroom wrap cursor, headroom wrap aider, headroom wrap copilot, and headroom wrap openclaw. The OpenClaw integration installs Headroom as a ContextEngine plugin.
Cross-agent memory and learning
Headroom includes a shared memory store that persists compressed context across agent sessions. When you run Claude Code and Codex on the same project, previously compressed tool outputs are deduplicated rather than re-compressed.
headroom learn mines failed agent sessions and writes corrections to instruction files. It scans conversation history for tasks where the agent needed multiple attempts, identifies what context would have helped on the first try, and writes that context to CLAUDE.md, AGENTS.md, or GEMINI.md. This turns repeated failures into pre-loaded context for future sessions.
Latency: net positive on all workloads
Compression adds overhead - the question is whether the token savings outweigh it. Headroom's numbers show a net latency win on every workload tested. Compression takes 1-2ms for small payloads and up to 2 seconds for 100K-token inputs, but the LLM inference time saved by sending fewer tokens is always larger:
| Scenario | Compress (ms) | LLM time saved (ms) | Net benefit |
|---|---|---|---|
| 100 search results | 189 | 261 | +72 ms |
| 500 search results | 943 | 1,461 | +518 ms |
| 1,000 search results | 2,012 | 2,969 | +957 ms |
These use Claude Sonnet pricing ($3.00/MTok input). The token savings translate directly to lower API costs - approximately $26 saved per 1,000 requests for the 100-result case, scaling to $297 per 1,000 requests at 1,000 results.
Open source, local-first
Headroom is Apache 2.0 licensed. Everything runs locally - no data leaves the machine. The headroom proxy command starts a local server on port 8787. The headroom mcp install command registers MCP tools in the local environment. Compression, memory, and learning all operate on the machine where the agent runs.
Install with pip install "headroom-ai[all]" (Python 3.10+) or npm install headroom-ai (TypeScript). Docker images are available at ghcr.io/chopratejas/headroom:latest. Granular extras let you install only what you need: [proxy], [mcp], [ml], [code], [memory].
[^1]: Headroom on GitHub. chopratejas. [^2]: Headroom documentation. Architecture, CCR, benchmarks. [^3]: Kompress-base model on HuggingFace. [^4]: Sharbel. "The 10 fastest growing GitHub repos this week." X. June 6, 2026.