Headroom Compresses Agent Context by Up to 95% Without Losing Answers

Most agent context is boilerplate. Every tool call, database query, file read, and RAG retrieval produces output that is 70-95% structural noise - JSON wrappers, passing log lines, unchanged diff context, redundant search results. The LLM pays to process it all.

Headroom compresses that noise before it reaches the model. It sits between your agent and the LLM provider, intercepting messages, compressing them by content type, and forwarding an optimized request. The LLM sees less, responds faster, and costs less - while producing the same answers.

The project launched on June 6, 2026 by Tejas Chopra and gained 12,000 GitHub stars in its first week, landing at #2 on the fastest-growing repos list for that period.

How it works

Headroom runs a three-stage pipeline on every request.

Stage 1: CacheAligner. Provider KV caches only hit when message prefixes stay identical. CacheAligner stabilizes those prefixes so Anthropic's 90% read discount on cached tokens actually applies. Without it, even small prefix drift causes cache misses.

Stage 2: ContentRouter. Auto-detects content type - JSON, source code, logs, search results, diffs, HTML, plain text - and routes each to the optimal compressor.

Each compressor uses a different strategy. SmartCrusher, which handles JSON tool outputs where most savings occur, runs field-level statistical analysis - variance, uniqueness, change points - and selects a representative subset using the Kneedle algorithm on bigram coverage. Errors, anomalies, and distribution boundaries are preserved unconditionally. No keyword matching. A FATAL log line survives because its field variance marks it as an outlier, not because it matches a pattern.

CodeCompressor uses tree-sitter for AST-aware compression across Python, JavaScript, Go, Rust, Java, and C++. It preserves function signatures and collapses bodies. Kompress, for plain text, runs ModernBERT token classification to remove redundant tokens while preserving meaning.

Stage 3: IntelligentContext. If the conversation still exceeds the model's context window, every message is scored on six dimensions - recency, semantic similarity, learned importance, error indicators, forward references, and token density. The lowest-scored messages are dropped first. Tool calls and their responses are always dropped as atomic units.

Real numbers

The Headroom docs include benchmarks from production agent traces:

Reversible compression (CCR)

Aggressive compression raises an obvious question: what if the LLM needs the data that was removed? Headroom addresses this with CCR - Compress-Cache-Retrieve. Compressed content is stored in a local cache. The LLM gets a headroom_retrieve tool it can call when it needs full originals. Nothing is permanently lost.

The CCR store also enables cross-agent memory. Multiple agents - Claude, Codex, Gemini - can share a single compressed context store with automatic deduplication and agent provenance tracking.

Integration points

Headroom deploys four ways:

• Proxy: headroom proxy --port 8787 - zero code changes, any language. Point your agent at the proxy and it compresses everything transparently.
• Library: compress(messages) in Python or TypeScript, inline in any app.
• Agent wrap: headroom wrap claude|codex|cursor|aider|copilot - one command wraps existing agent CLI tools.
• MCP server: exposes headroom_compress, headroom_retrieve, and headroom_stats tools for any MCP client, including Hermes Agent. Register the server in Hermes Agent's MCP configuration and any agent gets compression.

For Hermes Agent specifically, the MCP server path means no code changes. Add the server to config.yaml and every conversation gets compressed before it reaches the model.

What gets caught

CacheAligner is the component most likely to get missed in initial setup. Without it, messages varying in structure - different tool call formatting, variable-length prefixes - cause provider KV cache misses even when the semantic prefix is identical. Headroom normalizes these before compression, so the cache discount applies consistently. The difference on long agent sessions can be significant: Anthropic's 90% cache discount on input tokens turns a $3.00/1M token rate into $0.30/1M for the cached portion.

For agents that make many tool calls - file reads, search queries, database lookups - the combination of SmartCrusher compression on outputs and CacheAligner on prefixes compounds. Compression cuts the total token volume. CacheAligner ensures the portion that remains is billed at the cached rate.

[^1]: Chopra, Tejas. "Headroom: The Context Optimization Layer for LLM Applications." GitHub. June 2026.

[^2]: Sharbel. "The 10 fastest growing GitHub repos this week." X. June 6, 2026.