Shrink agent inputs by 60–95% without breaking answers

What it does

Headroom intercepts everything an AI agent reads—tool outputs, logs, files, conversation history, and RAG results—and compresses it before the LLM ever sees it. It runs locally as a library, proxy, or MCP server, and routes each payload through a content-specific compressor: JSON gets flattened by SmartCrusher, code gets stripped to AST skeletons by CodeCompressor, and prose goes through a custom HuggingFace model called Kompress-base. A reversible layer called CCR keeps originals stored locally so the LLM can retrieve them on demand if it needs the full text.

The interesting bit

The project treats context compression as a systems problem, not just a text-minification trick. It aligns cache prefixes to hit provider KV caches, deduplicates memory across disparate agents like Claude and Cursor, and even mines failed sessions to write corrections back into agent configuration files. That is a lot of plumbing for what looks like a simple shrink ray.

Key highlights

• Claims 60–95% token reduction on real workloads like code search and incident debugging, with published before/after tables
• Multiple compression algorithms tailored by content type: JSON crusher, AST-aware code compressor, prose model, image router, cache aligner, and reversible CCR storage
• Cross-agent memory store that shares context between Claude Code, Codex, Cursor, and others with automatic deduplication
• headroom learn plugin system that analyzes failed agent sessions and updates CLAUDE.md or AGENTS.md files automatically
• Runs fully offline and local-first; data never leaves the box unless you send it to the LLM provider yourself

Caveats

• Sandboxed environments where local processes cannot run are explicitly unsupported
• Cursor integration still requires printing and pasting configuration once rather than being fully automatic
• Some benchmark tables omit baseline scores, making direct comparisons difficult

Verdict

Worth a look if you run agent-heavy workflows and burn through context windows on repetitive tool output. Skip if you already get native compaction from a single provider and never switch agents.