AI-agent tool · Apache-2.0

Headroom

Open-source, local-first context compression for AI agents, with library, proxy, MCP, and coding-agent wrapper modes.

Local context compression for AI agents

Headroom is an open-source, local-first context-compression tool for AI agents. It can reduce tool outputs, logs, RAG chunks, files, and conversation history before they reach a model—through a Python or TypeScript library, a local proxy, agent wrappers, or an MCP server.

Compression happens on the machine running Headroom. The project is licensed under Apache-2.0.

What it changes

agent or application
  → tool outputs · logs · RAG results · files · history
  → Headroom (local compression + retrieval)
  → model provider

Headroom routes JSON, source code, and prose through different compressors, preserves the original material locally for retrieval, and offers a proxy when changing application code is not the right integration point.

Start with the CLI

The current upstream quickstart recommends an isolated Python install for the CLI:

uv tool install --python 3.13 "headroom-ai[all]"
headroom deploy
headroom doctor

pip install "headroom-ai[all]" also installs the CLI. npm install headroom-ai is the TypeScript SDK only; it does not install the headroom command. Headroom requires Python 3.10+; the upstream install guide has platform, Docker, and persistent-install details.

Use it with Claude Code or Codex

Headroom’s current compatibility table lists both Claude Code and Codex as supported wrapper targets:

headroom wrap claude
# or
headroom wrap codex

The wrapper starts a local proxy and launches the selected coding agent configured to route through it. Undo a durable wrapper with headroom unwrap <tool>. Any OpenAI-compatible client can instead use headroom proxy.

Use it inline in Python

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%})")

Headroom also exposes MCP tools for compression, retrieval, and stats, and it supports TypeScript, proxy, middleware, and framework integrations in the upstream documentation.

Read the savings and quality claims carefully

The project publishes seeded offline examples built from real MCP-output formats: 21% reported savings for code search, 57% for one SRE-debugging scenario, 42% for codebase exploration, and 30% for issue triage. Those are useful reproducible examples—not a promise for every agent or prompt.

Savings depend on the workload. The README says repetitive JSON arrays and log lines can compress heavily, while prose, short exchanges, and already-dense output may see little or no reduction. Run headroom savings or your own controlled evaluation against the traffic you actually care about.

The upstream evaluation table includes a small N=100 comparison on selected benchmarks. It does not establish universally unchanged answer quality. Treat answer quality, retrieval behavior, latency, and token savings as properties to test in your own task and failure modes before relying on them in production.

Data and operational notes

Compression is local-first; the project says prompts, completions, code, and file paths are not sent for compression.
Its README also documents an anonymous telemetry beacon enabled by default for compression ratios, counters, provider/model IDs, OS, and architecture. It can be disabled with HEADROOM_BEACON=off, DO_NOT_TRACK=1, or --offline.
Headroom is most relevant to long agent sessions with substantial tool output. It is less compelling when a local process cannot run or a single provider’s native compaction already covers the needed case.

Links and evidence

Raw Markdown