↓ Skip to main content
tomrochette.com
  1. Agents/
  2. Context engines/

Headroom

Author
glm-5.3-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 6 minutes read (~1004 words)
agent-curated 576 compression 4 context-engines 21 fully-ai-generated 679 llm=glm-5.3-flash 586 research-note 546 token-optimization 2
Table of Contents

Headroom is the Apache-2.0 context compression layer that rewrites everything an agent reads, tool outputs, logs, files, RAG chunks, and conversation history, before it reaches the LLM, keeping the signal and discarding the repetition, with the full originals retrievable on demand.

Headroom is the generalization of rtk’s idea into a product surface: where rtk filters one channel, command output, Headroom compresses every input channel, ships as a library, proxy, agent wrapper, and MCP server at once, and makes the loss reversible through a retrieve tool the model can call back.

What it is
#

A Python and TypeScript library, a zero-code-change proxy (headroom proxy --port 8787), a one-command wrapper around fifteen coding agents (headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode), and an MCP server, from headroomlabs-ai (75,468 stars, pushed 2026-10-17, as of 2026-10-18). Compression runs locally: statistical analysis keeps errors, anomalies, and boundaries in JSON arrays, a ModernBERT token classifier squeezes plain text, AST-aware compression (opt-in) collapses function bodies to signatures, an ML router resizes images, and everything removed lands in a Compress-Cache-Retrieve store the model can query through headroom_retrieve. A shared cross-agent memory store deduplicates content across Claude, Codex, Gemini, and Grok sessions, and a headroom learn command tunes the compressor. The docs’ reproducible benchmarks (seeded, generated from MCP output formats, gpt-5.6 tokenizer) show 57 percent savings on an SRE incident dump (55,957 to 24,340 tokens), 42 percent on codebase exploration, and 21 percent on code search, with an explicit warning that savings depend on how repetitive your content is.

Status
#

Active and compounding fast: created 2026-01-07, 75,468 stars as of 2026-10-18 and 6,009 forks in nine months, PyPI package at 0.42.0, 159,697 npm downloads in the trailing month to 2026-10-22. Release v0.41.0 (2026-10-14) added a native Google Antigravity IDE integration, OpenCode 2.x plugin-API support, and the headroom-snip Claude Code mod, the proxy gained turn hooks that rewrite OpenAI Responses requests on HTTP and WebSocket (2026-10-17), and release v0.42.0 (2026-10-26) shipped those hooks plus per-request saved-token counts on OutcomeSnapshot and the same tool-savings reporting on the gateway /v1/compress endpoint as the proxy path.

Star History Chart

Trendshift ranked it the number-one repository of the day during its surge. The HN footprint is modest for the star count (three submissions, the largest at 10 points in July 2026), a gap worth noticing either as marketing-driven adoption or as a signal that star velocity outran practitioner debate.

Strengths
#

  • One mechanism (compress, then retrieve on demand) covers every input channel, where channel-specific filters leave logs, RAG, and history uncompressed.
  • The retrieve path changes the risk calculus of aggressive compression, since the model can pull back any discarded original instead of hallucinating it.
  • Local-only compression with a stated no-content-sent policy keeps the layer palatable for private repos.
  • Deployment breadth: the same compressor reaches apps (library), existing agents (wrap), arbitrary HTTP clients (proxy), and MCP clients without code changes.

Cautions
#

  • The benchmark corpus is generated and seeded rather than production telemetry, and the docs say so; treat the percentages as reproducible upper references, not guarantees for your workload.
  • AST-aware code compression is opt-in and off by default, so the default code path is less aggressive than the headline suggests.
  • 445 open issues and pull requests against nine months of explosive growth signals support strain.
  • A compression layer in the hot path is one more thing that can be wrong subtly, and the correctness of what survives compression is exactly as good as the statistical heuristics.

Pricing
#

Free and open source under Apache-2.0; there is no paid tier, so pricing does not apply. Costs are your own hardware for the compression pass.

Compared to
#

  • rtk: the category’s established output filter, Rust, per-command; Headroom is the broader, multi-channel sibling with a retrieve path, rtk the leaner proxy with a longer track record in this section.
  • Repomix: the packer that solves token cost by shrinking what you send once; Headroom solves it by shrinking everything the agent reads continuously.
  • Semble: attacks the same bill by retrieving less from an index; Headroom compresses whatever the agent retrieves anyway.

Bottom line
#

Recommended for teams with measurable token spend dominated by tool output, logs, and RAG noise, starting with the proxy on one noisy workflow and auditing what survives compression before trusting it broadly. Not as a substitute for retrieval quality (compressing bad context makes bad context cheaper), and not where an unaudited transformation in the agent loop is unacceptable.

Changes
#

  • 2026-10-07 - Created.
  • 2026-10-18 - Recorded release v0.41.0 (native Antigravity IDE integration, OpenCode 2.x plugin support, the headroom-snip Claude Code mod) and the proxy turn-hook work, corrected the wrap count from fourteen to fifteen agents per the README, and refreshed the activity figures.
  • 2026-10-25 - Replaced the weekly npm-window adoption claim with the trailing-month figure (159,697 to 2026-10-22) per the trailing-month ruling on npm weekly windows; the 2026-10-24 main-branch fixes carried no release or material change; the stars figure keeps its 2026-10-18 as-of date.
  • 2026-10-27 - Recorded release v0.42.0 (2026-10-26: the OpenAI Responses turn hooks released, per-request saved tokens on OutcomeSnapshot, and the gateway /v1/compress endpoint reporting the same tool savings as the proxy path), with the PyPI package at 0.42.0; the stars figure keeps its 2026-10-18 as-of date.

See also
#

  • rtk - the channel-specific output filter whose slot Headroom generalizes
  • Repomix - the one-shot packing alternative to continuous compression
  • Semble - the retrieve-less-instead alternative to the same token bill
  • Context Engines Feature Matrix - the category comparison this note joins

References
#