Headroom: The Context Compression Layer for AI Agents
Compress tool outputs, logs, files, and RAG chunks before they reach the LLM, saving 15-20% tokens for coding agents and 60-95% for JSON, with identical answers.
- Source repo
- headroomlabs-ai/headroom
- Stars
- ★ 76k
- Last updated
- 1d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 59/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer using Claude Code or Cursor daily wants to reduce context tokens for tool outputs by 15-20% without changing answers.
- Not a fit if
- Teams happy with one provider's native compaction and no cross-agent memory
- Sandboxes where local processes cannot run
- Short chats or already-dense payloads that see little reduction
- Source review
- 59/100 · Major gaps
What does this agent do, and when should you use it?
Headroom is a local-first context compression layer for AI agents that reduces the number of tokens sent to an LLM without changing the answers. It provides Python and TypeScript libraries, a drop-in proxy, an MCP server, and cross-agent memory. The core pipeline uses a ContentRouter to detect content type, then compresses with SmartCrusher for JSON, CodeCompressor (AST-aware) for code, and Kompress-v2-base for prose. Compression is reversible via a CCR mechanism that caches originals locally, retrievable on demand. The project supports integration with coding agents like Claude Code, Codex, Copilot, and Cursor through a proxy, and transparently handles Anthropic and OpenAI-compatible APIs. It also includes headroom learn to mine failed sessions and write corrections to memory files like CLAUDE.md.
Headroom performs several concrete operations before content reaches the LLM. As a library, it offers compress() to process messages directly. As a proxy, headroom proxy --port 8787 runs a drop-in proxy for any client. As a wrapper, headroom wrap claude launches a local proxy, installs semantic code navigation via Serena, and configures the agent to route through Headroom. It uses a ContentRouter to classify input, then compresses with SmartCrusher (JSON), CodeCompressor (AST), or Kompress-v2-base (text). Output-side token reduction includes verbosity steering and reduced thinking effort, enabled via HEADROOM_OUTPUT_SHAPER. It serves an MCP server with tools like headroom_compress, headroom_retrieve, and headroom_stats. It mines failed sessions with headroom learn and writes corrections to CLAUDE.md, AGENTS.md, or GEMINI.md.
- A developer using Claude Code or Cursor daily wants to reduce context tokens for tool outputs by 15-20% without changing answers.
- An SRE dealing with huge JSON responses uses SmartCrusher to achieve 60-95% token reduction.
- A RAG pipeline engineer compresses large document chunks before sending them to the LLM.
- A team using multiple agents (Claude, Codex, Gemini) shares memory across them with cross-agent memory.
- A CI environment runs coding agents and wants to cut token costs for automated workflows.
- A developer integrates with Anthropic or OpenAI APIs transparently via the proxy or SDK adapters.
How do you install or deploy this agent?
Headroom installs as a Python tool via pip or uv, with a TypeScript SDK. The Python CLI provides full features; the TypeScript SDK is library-only.
How do you use this agent?
After installation, run Headroom in your preferred mode. Start a zero-code proxy with headroom proxy --port 8787. Wrap a coding agent with headroom wrap claude. Use headroom deploy for a turnkey setup. Verify with headroom doctor.
What are this agent's strengths and limitations?
- Local-first and reversible: data stays on your machine, and originals are retrievable via CCR.
- Content-aware compression: uses specialized compressors for JSON, code, and text.
- Agent-agnostic: supports Claude Code, Codex, Copilot, Cursor, and more via proxy and OpenAI compatibility.
- Output-side token reduction: shrinks what the model writes back, including verbosity steering and thinking budget cuts.
- Cross-agent shared memory: shares context across multiple agents with automatic deduplication.
- Setup overhead: wrapping an agent requires a local proxy and configuration, which may require debugging.
- Python version requirements: needs Python 3.10+ but 3.13+ for full dollar savings with LiteLLM.
- CPU requirement: x86 hosts need AVX2 for ONNX-backed features, limiting some older VMs.
- Performance overhead: compression adds latency to each request.
- Documented limitations: some paths are noted as smoke-tested but not fully validated (e.g., Windows/Linux credential storage).
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Headroom: The Context Compression Layer for AI Agents This agent | 59 · Major gaps | CLIFree + model costs | ★ 76k | 1d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| AOCI-CODE — a Git-versioned cognition index for coding agents | 52 · Major gaps | CLIFree + model costs | ★ 1.6k | 4d ago | Go | Codex · Claude Code |
| Loop Engineering | 69 · Some gaps | CLIFree + model costs | ★ 12k | today | TypeScript | Codex · Claude Code |
| Best of Agent Harnesses | 75 · Good | MCP serverFree + model costs | ★ 1.3k | today | Python | Claude Code · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: local-first operation, data stays on machine; passthrough mode for sensitive content; security policy documents no credential storage; dependencies have CVE fixes and constraints. Deductions: least privilege not explicitly addressed; user confirmation unclear for wrap operations; external effects (modifying user config) not fully documented; publisher identity unverified, source attribution unclear.
Evidence shows: README and pyproject.toml descriptions consistent; feature list clear; dependencies have version constraints and CVE fixes; CI tests and error handling mentioned. Deductions: no specific failure message examples; dependency availability not fully verified (e.g., model downloads rely on external services).
Evidence shows: clear target audience (developers, teams); multiple usage scenarios (library, proxy, MCP); capability boundaries clear (supports many agents and frameworks); trigger conditions explicit (wrap, proxy commands); environment fit good (Python 3.10+, multiple OS). Deductions: not all environment limitations detailed (e.g., Windows support limited).
Evidence shows: clear information architecture with docs and llms.txt; detailed install notes; stable naming (headroom-ai); examples and FAQ present; known limitations mentioned (e.g., sandbox); Apache-2.0 license; version and changelog; maintenance responsibility stated (community support). Deductions: publisher identity unverified, maintenance responsibility unclear.
Evidence shows: high output usability (originals retrievable after compression); clear marginal value (token savings); cost-benefit supported by data (savings percentages). Deductions: no independent verification; cost-benefit data may come from internal tests.
Evidence shows: performance data in README has benchmarks and reproduction commands; multiple sources (README, pyproject, CI) corroborate; facts and inferences separated (e.g., output savings are estimates). Deductions: limited cross-source verification; no third-party independent verification.
- The agent modifies user configuration files (e.g., CLAUDE.local.md); ensure backups or know how to undo.
- Depends on external model downloads (e.g., HuggingFace); may not work in offline or restricted network environments.
- Publisher identity is unverified; use with caution and review code and dependencies for security.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.41.0 Release v0.41.0
Release notes excerpt
[0.41.0](https://github.com/headroomlabs-ai/headroom/compare/v0.40.0...v0.41.0) (2026-10-13) Features * antigravity: add native Google Antigravity IDE integration ([#3817](https://github.com/headroomlabs-ai/headroom/issues/3817)) ([cd4367b](https://github.com/headroomlabs-ai/headroom/commit/cd4367b040bf80b7358f100da54994f6d5fbfcfe)) * opencode: support the OpenCode 2.x plugin API ([#3999](https://github.com/headroomlabs-ai/headroom/issues/3999)) ([1d4b357](https://github.com/headroomlabs-ai/headroom/commit/1d4b357ca745549382e1ed9a3a6d39b5df52d3d5)) …View on GitHub ↗ -
v0.40.0 Release v0.40.0
Release notes excerpt
[0.40.0](https://github.com/headroomlabs-ai/headroom/compare/v0.39.1...v0.40.0) (2026-10-06) ⚠ BREAKING CHANGES * proxy: read HEADROOM_LICENSE and make usage reporting opt-in ([#3857](https://github.com/headroomlabs-ai/headroom/issues/3857)) * drop the crewai extra to remove chromadb from the lockfile ([#3870](https://github.com/headroomlabs-ai/headroom/issues/3870)) Features …View on GitHub ↗ -
v0.39.1 Release v0.39.1
Release notes excerpt
[0.39.1](https://github.com/headroomlabs-ai/headroom/compare/v0.39.0...v0.39.1) (2026-09-26) Bug Fixes * proxy: stop the 0.39.0 TPM limiter from refusing large-context requests forever ([#3806](https://github.com/headroomlabs-ai/headroom/issues/3806)) ([7968122](https://github.com/headroomlabs-ai/headroom/commit/7968122658c31c06ef3e5b1fe7911c8cb0a79ade))View on GitHub ↗