Headroom Compresses Agent Context by 87% With No Accuracy Loss
Every tool call, file read, log dump, and RAG retrieval your agent processes carries significant overhead. A grep result spanning 17,765 tokens might contain two relevant lines. A build log with 200 passing tests and one failure still sends all 200 passing results to the model. Headroom - released last week and gathering 21K GitHub stars - addresses this directly: compress everything before it reaches the LLM.
Headroom sits between your agent and the model provider. When your agent reads a file, queries a database, or runs a terminal command, the output passes through Headroom's compression pipeline before hitting the context window. The model sees less noise, responds faster, and costs less. The originals remain retrievable on demand through a reversible store.
The Pipeline
Headroom runs three stages on every request:
Stage 1 - CacheAligner. Stabilizes message prefixes so provider KV caches hit consistently. Anthropic offers a 90% read discount on cached prefixes, but cache misses from minor prefix drift negate that. CacheAligner ensures stable prefixes across turns.
Stage 2 - ContentRouter. Auto-detects content type and routes to the correct compressor. JSON arrays go to SmartCrusher, source code to the AST-aware CodeCompressor, plain text to Kompress (a ModernBERT-based classifier), logs to LogCompressor, search results to SearchCompressor, and git diffs to DiffCompressor.
Stage 3 - CCR (Compress-Cache-Retrieve). Compressed content is stored locally. The model gets a headroom_retrieve tool and can fetch full originals when it needs more detail. Compression is aggressive but lossless - nothing is thrown away.
Compression by Content Type
Each compressor targets a specific content category with a different strategy:
| Content Type | Compressor | Method | Savings |
|---|---|---|---|
| JSON arrays (tool outputs) | SmartCrusher | Statistical analysis, keeps errors and boundaries | 70–90% |
| Source code | CodeCompressor | AST-aware via tree-sitter, preserves signatures | 40–70% |
| Build/test logs | LogCompressor | Keeps failures, drops passing noise | 80–95% |
| Search results | SearchCompressor | Ranks by relevance, keeps top matches | 60–80% |
| Plain text | Kompress | ModernBERT token classification | 30–50% |
| Git diffs | DiffCompressor | Preserves change hunks, drops unchanged context | 40–60% |
| Images | ML router | Selects optimal resize/quality tradeoff | 40–90% |
CodeCompressor is opt-in by default (disabled) since source code compression can change semantics. All other compressors run automatically with content-type detection.
Real Workloads
Headroom publishes benchmarks on four representative agent workloads. These are full-context comparisons, not isolated snippet tests:
| Workload | Before | After | Savings |
|---|---|---|---|
| Code search (100 results) | 17,765 | 1,408 | 92% |
| SRE incident debugging | 65,694 | 5,118 | 92% |
| GitHub issue triage | 54,174 | 14,761 | 73% |
| Codebase exploration | 78,502 | 41,254 | 47% |
The codebase exploration workload sees only 47% compression because a larger fraction of the context is source code, which CodeCompressor handles conservatively (disabled by default). The numbers above show CodeCompressor disabled - enabling it pushes code-heavy workloads higher.
Accuracy
Compression is useless if it changes the answer. Headroom's evaluation suite measures whether compressed context produces the same result as full context across four benchmarks:
| 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% | 19% compression |
| BFCL | Tool calling | - | 97% | 32% compression |
GSM8K shows identical accuracy at 0.870. TruthfulQA shows a +0.030 gain - possibly from removing noisy context that distracts the model from factual answers. SQuAD v2 and BFCL both hit 97% accuracy with compressed context at 19% and 32% compression respectively. Reproduce with python -m headroom.evals suite --tier 1.
Hermes Agent Integration
Headroom runs as an MCP server, which makes Hermes Agent integration a single command:
pip install "headroom-ai[all]"
headroom mcp install
This registers three MCP tools available to your Hermes Agent:
headroom_compress- compresses content inline during a sessionheadroom_retrieve- fetches original uncompressed content from the CCR storeheadroom_stats- reports token savings per session
Hermes Agent's MCP integration loads these tools automatically. Any tool output - file reads, terminal results, search retrievals - can route through Headroom's compression before entering context. The model decides when to call headroom_retrieve for full originals, meaning it only pays for tokens it actually needs.
For coding workflows, Headroom also wraps Claude Code and Codex CLI directly with cross-agent shared memory:
headroom wrap claude --memory
headroom wrap codex --memory
The --memory flag enables a shared store across agents - Claude and Codex see each other's compressed context, with automatic deduplication.
Deployment Modes
Headroom ships as a transparent proxy, a Python/TypeScript library, and an MCP server. The proxy mode requires zero code changes - point your agent's ANTHROPIC_BASE_URL or OPENAI_BASE_URL at localhost:8787 and every request is compressed automatically. The library mode gives more control: call compress(messages) inline and inspect result.tokens_saved and result.compression_ratio programmatically.
The project is Apache 2.0 licensed. All compression runs locally - no data leaves your machine. The full pipeline, including the Kompress-base ModernBERT model, ships in the [all] extras install.
[^1]: Sharbel. "The 10 fastest growing GitHub repos this week." X. June 6, 2026. [^2]: Tejas Chopra et al. "Headroom - Context Compression Layer for AI Agents." GitHub. [^3]: Headroom. "Documentation." chopratejas.github.io.