headroomlabs-ai/headroom

Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens. Compression runs on your machine; no prompt or file content is sent anywhere to be compressed.

What it does

• Library — compress(messages) in Python or TypeScript, inline in any app.
• Proxy — headroom proxy --port 8787, zero code changes, any language.
• Agent wrap — headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode in one command; undo with headroom unwrap .
• MCP server — headroom_compress, headroom_retrieve, headroom_stats for any MCP client.
• Cross-agent memory — one shared store across Claude, Codex, Gemini and Grok, with automatic dedup.
• headroom learn — mines failed sessions and writes corrections to CLAUDE.local.md (default, gitignored), CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md.
• Output token reduction — trims what the model writes back, not only what you send. See below.
• Reversible (CCR) — originals are cached locally and retrieved on demand.

How it works

 Your agent / app
   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
        │   prompts · tool outputs · logs · RAG results · files
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Headroom   (runs locally — your data stays here)  │
    │  ────────────────────────────────────────────────  │
    │  CacheAligner  →  ContentRouter  →  CCR            │
    │                    ├─ SmartCrusher   (JSON)        │
    │                    ├─ CodeCompressor (AST)         │
    │                    └─ Kompress-v2-base (text, HF)  │
    │                                                    │
    │  Cross-agent memory  ·  headroom learn  ·  MCP     │
    └────────────────────────────────────────────────────┘
        │   compressed prompt  +  retrieval tool
        ▼
 LLM provider  (Anthropic · OpenAI · Bedrock · …)

• ContentRouter detects the content type and selects a compressor for it.
• SmartCrusher / CodeCompressor / Kompress-v2-base handle JSON, source code and prose respectively.
• CacheAligner flags volatile content that would bust a provider KV-cache prefix. It never rewrites prompts.
• CCR stores originals locally so the model can call headroom_retrieve when it needs the full text.

→ Architecture · CCR · Kompress-v2-base model card

Get started (60 seconds)

# 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)

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

Launch a wrapped agent session each time, so the setup runs. headroom wrap starts a local proxy, installs Serena for semantic code navigation, and launches the agent configured to route through Headroom. For Claude Code, Serena is registered for the wrapped project only (as a local-scope MCP server in ~/.claude.json). Use --code-memory-scope user to make it available in every project, or --code-memory none to skip it. headroom unwrap removes either registration.

The headroom CLI ships only in the PyPI package. The npm headroom-ai package is the TypeScript SDK — a library you import (import { compress } from 'headroom-ai') — and provides no headroom command.

Proof

Four scenarios built from real MCP server output formats, measured with the provider tokenizer and the shipped compress(). Seeded and offline, so you get the same numbers we did:

uv run python benchmarks/index_proof_table.py --seed 20260902

Savings scale with how repetitive the payload is. Repeated JSON arrays and log lines clear 90% in benchmarks/bench_latency.py; prose and already-dense output compress very little. Run headroom savings against your own traffic for the number that applies to you.

Compression costs well under a millisecond — 0.21 ms p50 on a 10K-token JSON search result, 1.4 ms at 100K tokens — so it does not show up in agent latency.

Accuracy. python -m headroom.evals suite --tier 1:

At N=100 a delta of ±0.03 falls inside the confidence interval, so TruthfulQA shows no detectable difference rather than an improvement. Methodology →

Output token reduction

Everything above shrinks the prompt you send. You also pay for every token the model writes back, and on Opus-class models output costs 5× input. Much of that output is ceremony: “Great, let me…” preambles, code re-printed straight back at you, and deep reasoning spent on routine steps like reading a file.

Headroom trims it from the proxy, with no change to your code:

• Verbosity steering appends a short “be terse, don’t restate context” note to the end of the system prompt, so your prompt cache still hits.

It applies to Anthropic /v1/messages and to OpenAI-compatible /v1/chat/completions and /v1/responses, with the same output_shaper:* labels on all paths.

export HEADROOM_OUTPUT_SHAPER=1     # off by default
headroom proxy --port 8787

Already running a proxy? These switches are read live on every request, so a proxy that headroom wrap reused rather than started would not see a value you export afterwards — its environment was snapshotted at launch. headroom wrap hot-syncs your current settings to the running proxy over a loopback POST /admin/runtime-env, so they take effect with no restart and no dropped requests. On a shared proxy these overrides are global; the last explicit setting wins.

Terseness you didn’t have to configure. People rarely state how terse they want answers — they show it, by interrupting long replies or moving on before they could have read them. headroom learn --verbosity reads past sessions and picks the level:

headroom learn --verbosity            # dry run — preview what it found
headroom learn --verbosity --apply    # save it and apply it to the running proxy

A proxy in cache mode (the default) never re-reads the learned level, because a level that changes mid-conversation would bust the prompt cache. There --apply pins it with HEADROOM_VERBOSITY_LEVEL; set that variable yourself to keep it after a restart.

Measuring it. Output savings are counterfactual — we never see what the model would have written — so Headroom reports an estimate with a confidence range and labels it as one:

headroom output-savings
# Reduction: 31.7%  (95% CI 27.7% … 35.7%)   [estimated]

For a measured number instead, hold out 10% of conversations as an unshaped control: export HEADROOM_OUTPUT_HOLDOUT=0.1. The dashboard’s Output Tokens Saved card then reads measured rather than estimated, with the band.

→ Output token reduction

Agent compatibility

[^third-party-upstream]: headroom wrap routes OpenAI-compatible traffic to the default upstream (https://api.openai.com/v1). For a third-party OpenAI-compatible provider (DeepSeek, Together, OpenRouter, a self-hosted gateway), pass --openai-api-url https://api.deepseek.com/v1 — or set OPENAI_TARGET_API_URL before wrapping — otherwise your provider key is sent to OpenAI and rejected with 401 Incorrect API key provided. See OpenCode + DeepSeek.

Any OpenAI-compatible client works through headroom proxy. MCP-native clients: headroom mcp install. Undo durable wrapping with headroom unwrap (claude, copilot, codex, grok, kimi, omp, opencode, openclaw, zcode). Registry authors should use the canonical server.json rather than reconstructing the headroom mcp serve contract from prose.

For Anthropic /v1/messages, --mode cache skips automatic --memory context injection so the provider prefix remains stable. OpenAI chat/responses and Gemini append memory to the live-zone tail. Use --mode token when you need automatic memory context on the Anthropic path.

When to use · when to skip

Good fit if you run coding agents daily and want savings without touching your code, work across several agents and want one shared memory, or need compression that is reversible — originals stay retrievable through CCR for the configured TTL.

Skip it if you only use one provider’s native compaction and don’t need cross-agent memory, or work in a sandbox where local processes can’t run.

Headroom pays off on long agent sessions with heavy tool output. Short conversational exchanges, prose, and already-dense payloads see little or no reduction, and blocks under min_input_words come back byte-identical. Limitations has the full list.

Install

uv tool install --python 3.13 "headroom-ai[all]"  # CLI, isolated app env
pip install "headroom-ai[all]"                    # Python, everything — includes the CLI
npm install headroom-ai                           # TypeScript SDK (library only)
docker pull ghcr.io/headroomlabs-ai/headroom:latest

Granular extras: [proxy], [mcp], [ml] (Kompress-v2-base), [code], [memory], [vector] (optional HNSW backend — needs a C++ toolchain, not in [all]), [relevance], [image], [agno], [langchain], [evals], [pytorch-mps] (Apple-GPU memory-embedder offload — set HEADROOM_EMBEDDER_RUNTIME=pytorch_mps). Requires Python 3.11+.

[all] covers the core stack but not the framework adapters. Install those separately: pip install "headroom-ai[langchain]", and likewise [agno], [strands], [anyllm], [bedrock].

→ Installation guide — Docker tags, persistent service, PowerShell, devcontainers.

headroom learn

headroom learn mines failed sessions and writes corrections to CLAUDE.local.md (default, gitignored; use --target CLAUDE.md for the shared team file), AGENTS.md or GEMINI.md. → Failure learning

Telemetry

An anonymous beacon is on by default. It reports how compression behaved: ratios, counters, provider and model IDs, OS and architecture. It never sends prompts, completions, code or file paths. It exists so we can see when a release regresses a compression ratio across real workloads rather than only our own test corpus.

Turn it off with HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off, the DO_NOT_TRACK=1 convention, or HEADROOM_OFFLINE=1. The full field list is in the proxy docs.

Headroom for teams

Not seeing the savings you want? Headroom OSS is a framework. It was built to show what’s possible on one developer’s laptop, so it saves less than it could. We are building bigger savings for teams and enterprises in Headroom Enterprise, which adds:

• More cost savings
• Tokens secured
• On premise deployment
• Deep attribution
• And many more features

If you’re a team or an enterprise, talk to us: [email protected] · headroomlabs.ai

Everything in this repo stays open source under Apache 2.0.

Documentation

Compared to

Headroom runs locally, covers every content type, works with every major framework, and is reversible.

Headroom is the proxy, and it compresses everything flowing through it whatever sits upstream. Our recommended companion is Serena for semantic code navigation, installed by default when you wrap an agent, plus Ponytail if you want leaner model output. Everything else is your call — attach a code-memory MCP, Graphify, Caveman, or any other MCP server, and Headroom compresses downstream of all of it.

Contributing

git clone https://github.com/headroomlabs-ai/headroom.git && cd headroom
uv sync --extra dev && uv run pytest

Devcontainers in .devcontainer/ (default, plus memory-stack with Qdrant and Neo4j). See CONTRIBUTING.md.

Community

• Discord — questions, feedback, war stories.
• Kompress-v2-base on HuggingFace — the model behind text compression.
• Claude Code status-line plugin — live token savings in your status line, by @Ship-Wright.

License

Apache 2.0 — see LICENSE.