Open sourcePython · ≈80k stars · Apache-2.0
Headroom
Context compression for coding agents.
Headroom compresses tool outputs, logs, files and RAG chunks before they reach the LLM — 20% fewer tokens for coding agents and 60–95% for other workloads. Context engineering as infrastructure: keeping the window usable as harnesses grow.
Pros & cons
Each point cites its sources and says what kind of evidence backs it. A second reviewer tried to refute every claim before it was kept.
Pros
- DocsCompresses tool outputs, logs and files locally. It runs as a library, a proxy, an MCP server, or via `headroom wrap` for Claude Code, Codex, Cursor, Aider, Cline and others.[1]
- DocsCompression is reversible: originals are cached and the model can fetch them by hash with headroom_retrieve. History is trimmed as whole tool-call units, so function calls are not broken.[1][2][3]
- User reportsHN users say it noticeably stretches token budgets and subscription windows (one of those comments includes an affiliate link).[1][2]
- MetadataApache-2.0, about 78k stars, and very active (v0.42.0 on Oct 26, 2026).[1]
Cons
- Independent testIn one user's small eval matrix (RTK, Headroom, both, or neither), running with neither was clearly best: fewer tokens per turn were offset by more turns.[1]
- Independent testA cost write-up cited on HN measured only about 3-4% real API savings from RTK, caveman mode and Headroom combined, with no data on quality.[1]
- User reportsSome users noticed no difference in practice, and one called this class of tool mostly vaporware without independent benchmarks.[1][2]
- DocsAt launch the author said SmartCrusher is deliberately conservative and focused on JSON arrays, and that heuristic relevance scoring can drop the one item you needed.[1]
- Best for
- Agents whose context is dominated by large JSON, log or search payloads, especially with small context windows or capped subscriptions.
- Watch out for
- Measure end-to-end task cost and success rather than tokens per turn; savings can vanish if the agent needs more turns.
Assessed Oct 29, 2026 · adversarially reviewedSuggest a correction
People
Engineer
Creator and lead maintainer, Headroom
Cost & limits
Activity
- Last push
- · yesterday
- Latest release
- v0.44.0
· 11d ago - Last 90 days
- 10 releases
v0.44.0Release v0.44.0
· 11d ago0.44.0 (2026-11-09) ⚠ BREAKING CHANGES packaging: keep PyTorch extras out of all (#4067) Features pipeline: say whose request an OutcomeSnapshot is (#4698) (a2bcbd1) providers: add Hermes agent wrap support (#934) (7877241) proxy/model-router: add shadow mode…
v0.43.1Release v0.43.1
· 2w ago0.43.1 (2026-11-05) Bug Fixes ccr: keep the in-memory order queue from evicting re-stored entries (#4545) (c6f5bf9) memory: read the relation key the memory_save schema advertises (#4647) (7592e68) memory: replace the HNSW vector when a memory is re-indexed (#4649) (ee638f9)…
v0.43.0Release v0.43.0
· 2w ago0.43.0 (2026-11-05) ⚠ BREAKING CHANGES mcp: port MCP servers to SDK 2.x (#4603) Features ccr: answer headroom_retrieve on streaming chat completions (#4631) (31dcaf4) mcp: port MCP servers to SDK 2.x (#4603) (ee2252a) plugins: headroom skill for Claude Code, Codex, Copilot and…
v0.42.0Release v0.42.0
· 3w ago0.42.0 (2026-10-26) Features pipeline: put per-request saved tokens on OutcomeSnapshot (#4231) (8cedf7b) proxy: let turn hooks rewrite OpenAI Responses requests on HTTP and WebSocket (#4232) (fbf7bc3) proxy: report the same tool savings on gateway /v1/compress as the proxy path…
v0.41.0Release v0.41.0
· 5w ago0.41.0 (2026-10-13) Features antigravity: add native Google Antigravity IDE integration (#3817) (cd4367b) opencode: support the OpenCode 2.x plugin API (#3999) (1d4b357) plugins: add headroom-snip Claude Code mod that animates compression (#3980) (17abee2) proxy: native…
Checked against GitHub on Nov 21, 2026. Release notes are shortened to plain text.
Neighbours on the workbench
JavaScript · ≈308k stars · MIT
affaan-m/ECC
Agent harness performance optimization system: skills, instincts, memory and security for coding agents.
Maintained by Affaan Mustafa
TypeScript · ≈265k stars · MIT
NousResearch/hermes-agent
The agent that grows with you.
Maintained by Nous Research
v0.23.3releasedTypeScript · ≈205k stars · AGPL-3.0
firecrawl/firecrawl
Turn websites into clean markdown for LLMs and agents.
Maintained by Firecrawl (formerly Mendable)
Connections
Relations from the Harness Hub knowledge graph, as charted in the State of Harness reports.
Maintained by · 1
- Headroom LabsOrganisation
