headroomlabs-ai/headroom
Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
How headroom is put together
Headroom is a context-compression layer for LLM/AI agents that reduces token counts of prompts, tool outputs, logs, and RAG chunks before they reach the model, and reversibly caches originals (CCR) for on-demand retrieval. It ships as a Python package (`headroom-ai`, the `headroom` CLI, SDK, and proxy) built on a Rust core via maturin/pyo3, plus a TypeScript SDK on npm. The data flow routes content through a ContentRouter that selects a compressor (SmartCrusher for JSON, CodeCompressor for AST/code, Kompress-v2-base for prose), with a local proxy that sits between agents and providers (Anthropic, OpenAI, Bedrock, Vertex) and exposes an MCP server. It is local-first: content is compressed on the user's machine and originals are stored locally in a CCR store (SQLite/Redis/in-memory).
Languages
Frameworks
Datastores
Infrastructure
Major components
headroom-core (Rust)
Core compression transforms and types: SmartCrusher (JSON), CodeCompressor (tree-sitter AST), CCR store backends (SQLite/Redis), relevance embedding scorer, and content-detection signals.
headroom-proxy (Rust)
Native async HTTP proxy crate (axum/tokio) that sits between agents and LLM providers, applying compression and provider routing/signing.
Python SDK & CLI
The `headroom` package exposing compress(), the Click-based CLI (proxy, wrap, deploy, doctor, mcp), config models, and pipeline orchestration.
CCR (Compressed Context Retrieval)
Reversibly caches original content locally and resolves <<ccr:hash>> markers via retrieval tools, with batch and marker-resolution submodules.
MCP server
Exposes headroom_compress, headroom_retrieve, and headroom_stats tools over stdio for MCP-compatible hosts (Claude Code, Cursor, Codex).
Cache / CacheAligner subsystem
Provider-specific cache handling (anthropic/openai/google), prefix tracking, dynamic content detection, and compression stores/feedback.
Provider backends & auth
Provider integrations (litellm, any-llm) and credential flows including GitHub Copilot OAuth, AWS SigV4/Bedrock, and GCP Vertex ADC.
headroom-parity / simulators (Rust)
Rust-vs-Python parity harness and workload simulators ensuring byte-equal behavior across the language boundary.
A small, focused week of reliability fixes across memory scans, file-read protection, and provider routing.
5 weeksWeek of 2026-08-24
Week of 2026-08-24latest
A small, focused week of reliability fixes across memory scans, file-read protection, and provider routing.
Week of 2026-08-17
A large release week shipping five versions with heavy security hardening, provider-compatibility fixes, and dependency upgrades.
Week of 2026-08-10
The busiest week of the stretch, unifying cost-savings reporting and fixing a wide range of proxy, memory, and installer issues.
Week of 2026-08-03
A performance-and-accuracy week that cut latency, expanded the savings-reporting beacon, and enabled context tool search by default.
Week of 2026-07-27
A compression-focused week that ported engines to Rust, expanded compression options, and fixed retrieval-marker handling.
Over the past several weeks the team pushed a very high-volume run of reliability and cost-accuracy work on Headroom, an AI proxy that sits between coding tools and model providers to compress context and cut spend. Big themes were making cost/savings reporting accurate and consistent across every path, hardening the proxy against crashes and data corruption, porting compression engines to Rust, and protecting file-read content so AI edits don't break. The most recent week narrowed to a small set of targeted bug fixes, suggesting the codebase is stabilizing after a large burst of feature and infrastructure work.
Week by week
2026-08-24A small, focused week of reliability fixes across memory scans, file-read protection, and provider routing.latest5 changes
Fix
Corrupt memory rows no longer crash a whole scan
A single bad row in the memory graph is now skipped instead of aborting the entire lookup, so unrelated data stays available.
Fix
Protect file reads from lossy compression
Raw file contents that the AI edits against are now kept byte-for-byte exact on the Copilot/Responses path to avoid broken edits and re-reads.
Fix
Safer, faster savings recording
The step that writes out cost-savings data was made atomic and moved off the main loop so it can't corrupt or slow things down.
Fix
Prevent concurrent sessions from overwriting settings
Running multiple wrap sessions at once no longer clobbers the shared local settings file.
Fix
Route managed Kimi Code through the proxy
The Kimi Code integration now correctly goes through Headroom's proxy like other providers.
2026-08-17A large release week shipping five versions with heavy security hardening, provider-compatibility fixes, and dependency upgrades.6 changes
Fix
Validate provider addresses on every path
Caller-supplied upstream endpoints are now checked everywhere they're resolved, closing a security gap.
Fix
Address external security assessment findings
Fixed a batch of seven web-security issues flagged by an outside review.
Fix
More accurate output-token counting
Output tokens are now counted from the actual text produced rather than raw network size, improving cost accuracy.
Fix
Return proper errors when an upstream can't connect
Exhausted connection retries now return a 502 error instead of a misleading success response.
Chore
Multiple releases and dependency bumps
Shipped versions 0.36.1 through 0.36.5 alongside a wave of routine library and toolchain updates.
Fix
Better auth and routing diagnostics
Sign-in detection and the doctor tool were fixed to report project-scoped routing correctly instead of false negatives.
2026-08-10The busiest week of the stretch, unifying cost-savings reporting and fixing a wide range of proxy, memory, and installer issues.6 changes
Refactor
Unified savings reporting
Cost-savings numbers were made consistent across stats, performance, metrics, and the dashboard so they all tell the same story.
Feature
Extensions can report their own savings and latency
Add-on components can now contribute their cost savings and timing into the shared reporting system.
Fix
Keep long-running memory use bounded
Tuned macOS memory allocation and fixed leaks so the proxy's memory footprint stays stable over time.
Fix
Prevent search crash from malformed memory data
Bad-shaped entity references are now cleaned up so they can no longer crash memory search.
Feature
Configurable fallback model for large contexts
Teams can now choose which model handles very large contexts via a setting.
Fix
Windows and Docker installer fixes
Stopped the installer from polluting the user's PATH and fixed container deployments to ship correct auth and paths.
2026-08-03A performance-and-accuracy week that cut latency, expanded the savings-reporting beacon, and enabled context tool search by default.6 changes
Refactor
Cut hot-path latency by 27%
Speed improvements from caching token counts, preloading at startup, and smarter JSON scanning made the proxy noticeably faster.
Feature
Hourly savings compaction and richer reporting
The reporting beacon now consolidates data hourly and breaks savings down by strategy.
Fix
Enable tool search by default and repair bad transcripts
Turned on context tool-search out of the box and fixed corrupted conversation records it depended on.
Fix
Report savings across all layers
The beacon now counts savings from every optimization layer, not just context compression.
Fix
Reliable shutdown and Ctrl+C exit
The proxy now shuts down gracefully and responds to Ctrl+C dependably.
Fix
Patch a security vulnerability in a dependency
Upgraded the h2 networking library to close a known CVE.
2026-07-27A compression-focused week that ported engines to Rust, expanded compression options, and fixed retrieval-marker handling.6 changes
Feature
Ported compression engines to Rust
Both the code-aware and prose compressors were reimplemented in Rust for a faster, matched-behavior version.
Feature
Added PHP support to the code compressor
The code-aware compressor can now understand and compress PHP source files.
Feature
Marker-free compression by default
The compression endpoint now defaults to cleaner output without inline retrieval markers.
Fix
Unbrick Serena on fresh installs
Stopped creating a config file that broke the Serena integration on new setups.
Fix
Route Codex Live voice through a dedicated transport
Live voice sessions now use their own connection path for correct handling.
Fix
Pin a dependency to prevent startup crashes
Capped the MCP library version to stop the server from crashing on launch.
Dependencies and code review
Dependency advisories
Security Watch
No known advisories across 0 scanned dependencies.
No known advisories in the scanned dependencies.
Code review
No concrete code-level issues confirmed.
Get this report every week for your repos.
GitZoid learns each repo, reports what changed, and flags what needs attention. One flat price for the whole team.
$19 a month, flat · First 10 outputs free · No card required