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 sixteen coding agents (headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|droid|zcode), an MCP server, and an opt-in output shaper that trims what the model writes back (verbosity steering at the system-prompt tail, off by default), from headroomlabs-ai (75,468 stars as of 2026-10-18, pushed 2026-11-11).
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,290 forks as of 2026-11-22, PyPI package at 0.45.0 (2026-11-22) across 208 releases, 160,130 npm downloads summed for 2026-10-14 to 2026-11-21 (four zero days in the window).
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), 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, and the v0.43 pair (both 2026-11-05) ported the MCP servers to SDK 2.x as a breaking change, answered headroom_retrieve on streaming chat completions, added a headroom skill plugin for Claude Code, Codex, Copilot and skills.sh, and put model-routing savings into headroom savings, with v0.43.1 fixing a CCR order-queue eviction and a memory-schema key.
Release v0.44.0 (2026-11-10) shipped the 2026-11-08 batch: headroom wrap droid adding Factory Droid as a sixteenth wrapped agent, a model-router shadow mode (HEADROOM_MODEL_ROUTER_LOG_ONLY) and unified multi-upstream routing for Anthropic Cloud and local oMLX, per-request cost_usd in /stats recent requests, shared Redis store availability in /health and /metrics, DeepSeek reported as its own provider, cumulative output tokens carried in savings history checkpoints, and max_body_bytes applied to the chat completions and responses routes, plus Hermes agent wrap support, a lossless /v1/compress mode that detects the provider by the request’s wire format, one conversation id per client conversation for turn hooks, per-request /stats metadata for token-authenticated callers, and the fix for the GHSA-mc2f-vg4v-2fh4 client-disconnect buffering advisory, under a breaking packaging change that keeps the PyTorch extras out of the default all install; a Vertex onboarding extra and the doctor IPv6 and HF-tokenizer fixes rode in from the 2026-11-06 to 11-07 batch, main’s unreleased 2026-11-10 to 11-11 fix round (a Gemini adapter accepting string contents, an OpenCode fix that stops routing non-LLM hosts to the proxy, Pi cwd resolution before injecting project tools, restored query-only semantic cache lookups, an OpenClaw circuit breaker opening on proxy failures, and installer-provenance verification in the build workflows) followed, and main’s unreleased 2026-11-14 security sweep (merged pull requests #4848 through #4870) hardens the proxy’s credential handling, keeping upstream credentials out of manifests, environment output, TOIN records, proxy logs, and 400 debug dumps, scoping memory tools to what the proxy injected and to the calling user, adding Host and Origin checks on the Streamable HTTP MCP transport, refusing OAuth2 token-endpoint redirects and untrusted browser origins, bounding brotli output, and withholding per-project savings from /stats network callers, with the follow-up 2026-11-14 to 11-15 round after it (the gateway turn accepting Gemini and Bedrock Converse request bodies, the private x-headroom-base-url guard extended to the async chat and responses paths, TrafficLearner’s SQLite reads scoped to its user id, and tag protection made linear-time).
Main’s unreleased 2026-11-17 batch (about thirty merged pull requests) follows the security sweep: memory fixes (frontmatter delimiters parsed on complete lines, content changes detected in incremental sync, the advertised memory_list tool actually dispatched, embedding dimensions validated before writes, older memories included in agent sync), proxy and routing fixes (the Rust front’s native Bedrock and Vertex routes made opt-in, Copilot requests kept on Copilot when an extension advises another provider, new VS Code chats kept on the Local harness so they reach the proxy, a TLS retry scoped to the window the request is being written), cache and lossless corrections (literal cache_control fields kept in the response-cache key, every parallel tool result replayed, cached CCR markers invalidated after store eviction, Go, nginx, klog, and access-log timestamps never folded, container-shaped strings kept as strings in lossless tables, scalar types verified in lossless message comparisons), content-router guards (cache_control markers protected inside tool_result content, list-form tool_result blocks kept on separate lines, source code kept out of the Kompress fallbacks), and telemetry work (beacon sessions split by harness, model, and day, modelled output savings booked per request as a token and dollar range, hourly beacon rollups parallelized), with PyPI unchanged at 0.44.0 across 207 releases so the batch is unreleased.
Main’s unreleased 2026-11-18 fix round follows: the /transformations/feed limit clamped to [1, 100], relay tasks kept when the same WebSocket handle re-registers, and the OpenAI Responses error frame given its type discriminator, with PyPI unchanged at 0.44.0 across 207 releases so the round is unreleased.
Release v0.45.0 (2026-11-22) then shipped every batch recorded above as unreleased (the 2026-11-14 security sweep through the 2026-11-19 to 11-20 round) plus new work: an opt-in system tray icon with a savings counter, dashboard, and update alert (#4726), an output-shaper steering level an extension can replace (defaulting to L3, #4877), and a repeatable OpenCode --extra-model flag for custom wrap-time models (#2364).
Main’s unreleased 2026-11-22 round follows that release: CI-security fixes (the gitleaks download verified against its release checksum and alert rules and locations kept out of the public CodeQL triage issue), the cc-switch reconciler keeping settings.json’s mode and symlink, the hook launcher’s Python fallback kept off the project directory, and Neo4j relationship types constrained to a single identifier.
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 as of 2026-10-18 had shrunk to 263 by 2026-11-11, but ten months of explosive growth still 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.
- An anonymous telemetry beacon is on by default; it reports compression ratios, counters, and provider and model IDs, never prompts or code, and turns off with
HEADROOM_BEACON=off,HEADROOM_TELEMETRY=off,DO_NOT_TRACK=1, orHEADROOM_OFFLINE=1, but default-on phoning home is a fact to weigh before adopting.
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.
- 2026-11-06 - Full rotation re-verification: every cited URL re-fetched (repository page and README, docs, PyPI, npm range, the HN thread, and the GitHub API all intact, the compression table and seeded benchmark rows unchanged); recorded the v0.43 pair (both 2026-11-05: the breaking MCP SDK 2.x port,
headroom_retrieveanswered on streaming chat completions, a headroom skill plugin for Claude Code, Codex, Copilot and skills.sh, model-routing savings inheadroom savings, and two CCR and memory fixes in v0.43.1) with PyPI at 0.43.1 across 206 releases; recorded the README’s new output-shaper surface (opt-in verbosity steering on what the model writes back, with counterfactual estimated savings and a holdout-measured mode) and its default-on anonymous telemetry beacon with documented opt-outs; refreshed the volatile numbers (6,173 forks, 318 open issues and pull requests, pushed 2026-11-06, 147,968 npm downloads summed for 2026-10-07 to 2026-11-06, eight zero days in the window); the stars figure keeps its 2026-10-18 as-of date. - 2026-11-07 - Recorded main’s unreleased 2026-11-06 to 11-07 fix batch (in-band Vertex failure diagnostics plus a
[vertex]backend extra, doctor IPv6 and case-variant loopback matching, the HF BatchEncoding token-count fix for silently reverted compression on HF-tokenized models, chatgpt-4o tokenizer aliases, learn-analyzer JSON hardening, Connection-named response-header dropping); no release since v0.43.1. - 2026-11-08 - Recorded main’s unreleased 2026-11-08 batch (
headroom wrap droidadding Factory Droid as a sixteenth wrapped agent, the model-router shadow mode and unified Anthropic Cloud plus local oMLX routing, per-requestcost_usdin/stats, Redis store health and metrics, DeepSeek as its own provider, cumulative output tokens in savings checkpoints, Bedrock credential refresh,max_body_byteson chat routes) and refreshed the volatile numbers (6,184 forks, 262 open issues and pull requests, pushed 2026-11-08, 171,340 npm downloads summed for 2026-10-08 to 2026-11-08); no release since v0.43.1, so the sixteenth wrap target is unreleased. - 2026-11-11 - Recorded release v0.44.0 (2026-11-10) shipping that batch with the sixteenth wrap target, plus Hermes agent wrap support, a lossless
/v1/compressmode with provider detection by the request’s wire format, per-conversation turn-hook ids, token-authenticated/statsmetadata, and the GHSA-mc2f-vg4v-2fh4 client-disconnect fix, under a breaking packaging change keeping the PyTorch extras out of the defaultallinstall (PyPI at 0.44.0 across 207 releases); recorded main’s unreleased 2026-11-10 to 11-11 fix round (Gemini adapter string contents, the OpenCode non-LLM-host proxy routing fix, Pi cwd resolution, query-only semantic cache lookups, the OpenClaw circuit breaker, installer provenance verification); corrected the wrap count from fifteen to sixteen agents per the released README; refreshed the volatile numbers (6,205 forks, 263 open issues and pull requests, pushed 2026-11-11, 138,573 npm downloads summed for 2026-10-12 to 2026-11-11); the stars figure keeps its 2026-10-18 as-of date. - 2026-11-14 - Recorded main’s unreleased 2026-11-14 security sweep (merged pull requests #4848 through #4870: upstream credentials kept out of manifests, environment output, TOIN, proxy logs, and 400 debug dumps, memory tools scoped to injected tools and to the calling user, Host and Origin checks on the Streamable HTTP MCP transport, the OAuth2 token endpoint refusing redirects, untrusted browser origins refused, brotli output bounded, per-project savings and quota stats withheld from /stats network callers); PyPI re-checked unchanged at 0.44.0 across 207 releases, so the sweep is unreleased.
- 2026-11-15 - Recorded main’s unreleased 2026-11-14 to 11-15 round (merged pull requests #4679 and #4841 through #4879: the gateway turn accepting Gemini and Bedrock Converse request bodies, the private
x-headroom-base-urlguard extended to the async chat and responses paths, TrafficLearner’s SQLite reads scoped to its user id, and tag protection made linear-time); PyPI re-checked unchanged at 0.44.0 across 207 releases, so the round is unreleased. - 2026-11-17 - Recorded main’s unreleased 2026-11-17 batch of about thirty merged pull requests (memory fixes for frontmatter delimiters, incremental-sync change detection, the advertised memory_list tool, embedding-dimension validation, and older memories in agent sync; the Rust front’s native Bedrock and Vertex routes made opt-in; Copilot provider-routing and new-VS Code-chat fixes; a TLS retry scoped to the request’s write window; cache fixes keeping literal cache_control fields in the response-cache key, replaying parallel tool results, and invalidating cached CCR markers after eviction; lossless guards for Go, nginx, klog, and access-log timestamps and container-shaped strings; content-router protections for cache_control markers in tool_result content and source code kept out of Kompress fallbacks; and beacon sessions split by harness, model, and day with per-request output savings booked as a token and dollar range); PyPI re-checked unchanged at 0.44.0 across 207 releases, so the batch is unreleased; refreshed the volatile numbers (6,259 forks, 271 open issues and pull requests, pushed 2026-11-17, 137,388 npm downloads summed 2026-10-13 to 2026-11-12, four zero days); the stars figure keeps its 2026-10-18 as-of date.
- 2026-11-19 - Recorded main’s unreleased 2026-11-18 fix round (the transformations-feed limit clamp, relay tasks kept on WS handle re-registration, the OpenAI Responses error-frame type discriminator); PyPI re-checked unchanged at 0.44.0 across 207 releases; forks and open issues and pull requests refreshed (6,282 and 304).
- 2026-11-21 - Recorded main’s unreleased 2026-11-19 to 11-20 fix round (an output-shaper guard against steering a body already steered on input, complete CCR hashes preserved across restarts, Ruby Logger timestamps never grep-folded in lossless mode, and an HNSW test skip when the probe fails); PyPI re-checked unchanged at 0.44.0 across 207 releases; forks and open issues and pull requests refreshed (6,277 and 326).
- 2026-11-22 - Recorded release v0.45.0 (2026-11-22, PyPI across 208 releases) shipping the recorded unreleased batches (the 2026-11-14 security sweep through the 2026-11-19 to 11-20 round) plus the opt-in tray icon with a savings counter, the extension-replaceable shaper steering level (default L3), and the repeatable OpenCode
--extra-modelflag; recorded main’s unreleased 2026-11-22 CI-security round (gitleaks checksum verification, CodeQL triage privacy, the cc-switch settings.json mode and symlink kept, the hook launcher’s Python fallback off the project directory, the Neo4j relationship-type fix); refreshed the volatile numbers (6,290 forks, 325 open issues and pull requests, pushed 2026-11-22, 160,130 npm downloads summed 2026-10-14 to 2026-11-21, four zero days); 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 #
https://github.com/headroomlabs-ai/headroom - repository, Apache-2.0 license, deployment surfaces, the agent wrap list, and the CCR store (fetched 200, 2026-10-18)
https://api.github.com/repos/headroomlabs-ai/headroom - stars, forks, open issues, created date, and push date for the as-of status (fetched 200, 2026-10-18)
https://docs.headroomlabs.ai/docs - the compression table by content type, the seeded benchmark table with its own caveats, and the framework integrations (fetched 200, 2026-10-18)
https://pypi.org/pypi/headroom-ai/json - the published package version 0.45.0 across 208 releases (fetched 200, re-fetched 2026-11-22)
https://api.npmjs.org/downloads/range/2026-10-14:2026-11-21/headroom-ai - 160,130 downloads summed for 2026-10-14 to 2026-11-21, four zero days in the window (fetched 2026-11-22)
https://api.github.com/repos/headroomlabs-ai/headroom/releases?per_page=6 - the release train: v0.45.0 published 2026-11-22 (re-fetched 2026-11-22)
https://hn.algolia.com/api/v1/items/48999841 - the largest Headroom thread, 10 points, July 2026, grounding the modest-HN-footprint observation (fetched 200, 2026-10-18)