Headroom: Local Context Compression for LLM Agents

What Headroom is

Headroom is an open-source context compression layer for LLM applications and coding agents. Its README says it compresses everything an agent reads (tool outputs, logs, RAG chunks, files and conversation history) before it reaches the LLM, with the goal of "same answers, fraction of the tokens". Compression runs on your own machine, and the README states that no prompt or file content is sent anywhere to be compressed.

The project targets two groups. Developers who run coding agents such as Claude Code, Codex, Cursor, Aider or OpenCode every day can put Headroom in front of them with one command and no code changes. Teams building their own LLM applications can call a compress() function from Python or TypeScript, or route traffic through Headroom's proxy. The repository is licensed under Apache-2.0 and written mainly in Python.

How it works

Headroom sits between your agent or app and the LLM provider. Requests pass through a pipeline that the README describes in four parts:

• ContentRouter detects what kind of content it is looking at and picks a compressor for it.
• SmartCrusher, CodeCompressor and Kompress-v2-base handle JSON, source code and prose respectively. SmartCrusher keeps error items, statistical outliers and first/last boundaries in JSON arrays; CodeCompressor is AST-aware for Python, JS/TS, Go, Rust, Java, C/C++, C# and PHP; Kompress-v2-base is the project's own model on Hugging Face, trained on agentic traces.
• CacheAligner flags volatile content that would break a provider's KV-cache prefix. The README stresses that it never rewrites prompts.
• CCR (reversible compression) stores originals locally, so the model can call headroom_retrieve when it needs the full text.

Compression is applied to the "live zone" only: fresh tool output and the latest turn. The frozen prefix of the conversation stays byte-identical so provider prompt caches keep hitting, and history is never dropped. Every entry point (the library, the SDK wrappers and the proxy) shares the same request lifecycle, with extension hooks for pipeline events, compression and proxy middleware.

Key features

• Library: compress(messages) in Python or TypeScript, inline in any app.
• Proxy: headroom proxy --port 8787 gives a drop-in endpoint for any OpenAI-compatible client, in any language.
• Agent wrapping: headroom wrap starts a local proxy and launches an agent configured to route through it. The compatibility table lists Claude Code, Codex, Grok CLI, Aider, Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe and others; headroom unwrap reverses durable wrapping.
• MCP server: headroom_compress, headroom_retrieve and headroom_stats tools for MCP clients, installed with headroom mcp install.
• Cross-agent memory: one shared store across Claude, Codex, Gemini and Grok, with agent provenance and automatic deduplication.
• Failure learning: headroom learn mines failed sessions and writes corrections to CLAUDE.local.md by default, or to CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md.
• Output token reduction: an opt-in output shaper appends a short terseness note to the end of the system prompt and lowers reasoning effort on turns that only resume after a tool result.
• Framework adapters: integrations for the Anthropic and OpenAI SDKs, Vercel AI SDK, LiteLLM, LangChain, Agno, Strands and ASGI apps.

Getting started

The README's quick start installs the CLI and picks a mode:

# 1 — Install
uv tool install --python 3.13 "headroom-ai[all]"  # CLI in a self-contained env
pip install "headroom-ai[all]"                    # Python — ships the `headroom` CLI
npm install headroom-ai                           # TypeScript SDK only — no CLI

# 2 — Pick a mode
headroom deploy                         # turnkey local deployment + agent config
headroom wrap claude                    # wrap a coding agent
headroom proxy --port 8787              # drop-in proxy, zero code changes
# or: from headroom import compress     # inline library

# 3 — Check it and watch the savings
headroom doctor                         # health check — confirms routing works
headroom perf
headroom dashboard                      # live savings (proxy must be running)

Used inline from Python, it compresses the message list before the provider call:

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

A Docker image is also published:

docker pull ghcr.io/headroomlabs-ai/headroom:latest

Note that the headroom CLI ships only in the PyPI package; the npm headroom-ai package is a TypeScript library with no command.

Use cases

• Long coding-agent sessions: wrap Claude Code, Codex or Aider so large test logs, search results and file dumps are compressed before each request.
• SRE and incident debugging with agents: log-heavy tool output is the kind of repetitive payload the README says compresses best.
• RAG and tool-heavy apps: call compress() or add the LiteLLM callback, LangChain wrapper or ASGI middleware to shrink retrieved chunks and JSON responses.
• Working across several agents: share one memory store between Claude, Codex, Gemini and Grok instead of re-explaining context in each tool.
• Measuring spend: headroom savings and the dashboard report savings on your own traffic rather than on published benchmarks.

How it compares

The README compares Headroom with hosted compression APIs such as Compresr and Token Co., and with OpenAI's provider-native compaction. In its table, those options either send text to a hosted API or cover only conversation history, while Headroom runs locally, covers tool output, RAG, logs, files and history, and is reversible through CCR. Those are the project's own characterisations.

The README's benchmark table reports savings of 21% to 57% across four scenarios built from real MCP output formats (for example 57% on an SRE incident debugging scenario), reproducible with a seeded script in benchmarks/. It also claims compression costs well under a millisecond (0.21 ms p50 on a 10K-token JSON result) and reports no detectable accuracy difference on GSM8K and TruthfulQA at N=100. The README is upfront that prose and already-dense output compress very little, and that short conversational exchanges see little or no reduction.

Things to know before adopting

• Telemetry is on by default: an anonymous beacon reports compression ratios, counters, provider and model IDs, OS and architecture, and the README says it never sends prompts, completions, code or file paths. Disable it with HEADROOM_TELEMETRY=off, HEADROOM_BEACON=off, DO_NOT_TRACK=1 or HEADROOM_OFFLINE=1.
• Open source plus Enterprise: the OSS edition is described as built for one developer on one laptop. A commercial Enterprise tier adds automatic model routing, prompt-injection and risky-tool-call detection, managed or VPC rollout and SSO. The README states everything in the repository stays Apache-2.0.
• Agent wrapping changes config: headroom wrap also installs Serena for semantic code navigation (registered per project for Claude Code by default); use --code-memory none to skip it.
• Third-party providers: when wrapping an agent that talks to a non-OpenAI OpenAI-compatible provider, pass --openai-api-url or set OPENAI_TARGET_API_URL; otherwise the README warns your provider key is sent to OpenAI and rejected.
• Platform notes: Python 3.10+ is required. The ONNX-backed features need AVX2 on x86 and fall back to simpler paths without it, and Intel macOS needs a system ONNX Runtime for source builds. Model and runtime downloads from Hugging Face and cdn.pyke.io may need attention behind corporate SSL inspection.
• Maturity: the repository was created in January 2026 and is moving quickly, so pin versions for shared setups. headroom update upgrades in place.

Project activity

As of October 2026 the repository has about 76,000 stars. It was created in January 2026, is written mainly in Python with a Rust core component, and is licensed under Apache-2.0, with pushes as recent as October 17, 2026. Packages are published to PyPI and npm as headroom-ai. Documentation is at docs.headroomlabs.ai and the source is at github.com/headroomlabs-ai/headroom.