1. What Headroom Is

Headroom is a context compression layer for AI agents. Before the LLM receives a request, it performs content-aware compression on tool output, logs, RAG chunks, file contents, and conversation history, cutting token usage to 5%–40% of the original while keeping answer quality as unchanged as possible.

Put simply, it solves the problem at the other end: CodeGraph helps an agent find faster what it should read; Headroom helps an agent read more economically what it has already found.

The project has been published to PyPI and npm as headroom-ai. It supports mainstream AI coding tools including Claude Code, Cursor, Codex, Copilot CLI, OpenCode, Cline, and Continue.

• Project repository: https://github.com/chopratejas/headroom
• Official documentation: https://headroom-docs.vercel.app/docs

2. Why You Need It

When an AI coding assistant is working, what really burns tokens is often not your question but what the tools return — a single grep with hundreds of lines, one API call with thousands of lines of JSON, one metrics query with 60 repeated data points. Most of that content is redundant for the current task, but the agent has to stuff it into the context in full.

Headroom’s approach is this: before the request goes to the LLM, pick a compressor by content type and strip out the redundancy; if it compresses too aggressively, the agent can still retrieve the original text on demand through CCR (Compress-Cache-Retrieve).

Without Headroom, the agent pays full price for redundant data; with Headroom, the agent reads a summary first and retrieves the details only when needed.

3. Comparison: With and Without Headroom

3.1 The Same Scenario, Two Paths

Suppose an agent is troubleshooting an SRE incident and has called 5 tools in a row — metrics, logs, deployments, and so on.

Without Headroom:

Tool returns 22,048 tokens → all of it enters the context
     → multi-turn conversation keeps accumulating → the context window fills up fast
     → cost grows linearly with conversation length

With Headroom:

Tool returns 22,048 tokens → SmartCrusher analyzes the statistical features
     → keeps anomalies, error entries, and head/tail samples → compresses to 2,190 tokens (about 90%)
     → the original text is cached and the agent can headroom_retrieve when needed
     → the model can still pinpoint the CPU spike and the key errors

3.2 Benchmarks

Real agent workloads (official README):

Accuracy retention (standard benchmarks):

Production telemetry (250+ agent instances, opt-in): cumulative savings of about 1.4 billion tokens; the compression pipeline’s median overhead is about 17ms, negligible next to LLM inference (usually 2–10 seconds).

The pattern is obvious: the heavier the tool output, the more JSON, and the longer the session, the greater the benefit from Headroom; short conversations and pure code-reading scenarios see limited gains.

3.3 When You Can Skip It

4. How It Works

Headroom inserts a compression pipeline into the LLM request path, going through these stages:

Agent request → CacheAligner → ContentRouter → Compressor → CCR cache
                ↓                ↓              ↓
           stable prefix cache   detect content type    SmartCrusher / CodeCompressor / Kompress
                ↓
           compressed prompt + retrieve tool → LLM Provider

4.1 ContentRouter: Pick a Compressor by Type

ContentRouter detects the content type of a message block and routes it to the corresponding compressor:

Compression is done under deterministic rules, with no extra LLM calls, so it is predictable and free of hallucination risk, with a median pipeline time of about 17ms.

4.2 SmartCrusher: Statistics, Not Truncation

SmartCrusher is the workhorse for JSON tool output. It does not simply chop off the tail of an array; it first does field analysis:

• Constant fields: if host is prod-1 in all 60 records, extract it into __headroom_constants
• Time-series change points: CPU jumps from 45% to 92% at the 45th point, keep the spike range
• Log clustering: merge similar error messages, keeping 1–2 entries per cluster
• Safety items: entries containing error / exception / failed are always kept

Example: 100 production log lines with the key error at line 67 — after compression 10,144 → 1,260 tokens, and 4/4 Q&A pairs still correct.

4.3 CCR: Reversible Compression

CCR (Compress-Cache-Retrieve) is Headroom’s core design:

1. Compress: SmartCrusher compresses 1000 entries down to 20
2. Cache: the original text goes into a local LRU cache and a hash is generated
3. Retrieve: the LLM calls headroom_retrieve(hash=...) to get the full text back

The proxy’s Response Handler handles retrieve tool calls automatically, transparently to the client. The Context Tracker also tracks compressed content across multi-turn conversations, proactively expanding it when a new question relates to old compressed data.

This means you can compress aggressively with zero risk of information loss — the worst case is that the agent asks for the original text back.

4.4 Live Zone Strategy

Headroom does not discard historical messages; it compresses only the latest content block (the live zone):

• Untouched: the system prompt, tool definitions, earlier conversation turns (keeps the provider prefix cache stable)
• Compressible: the latest user message, the latest tool result

This saves tokens without breaking Anthropic / OpenAI KV cache hits.

4.5 Output Token Optimization (Optional)

Beyond input compression, Headroom can also reduce the tokens the model writes back (Opus-class models charge 5x the input price for output):

• Verbosity steering: append a conciseness instruction to the end of the system prompt, without breaking the prompt cache
• Effort routing: lower thinking effort for routine continuations after a tool result, keep full effort for new questions and errors

1
2

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

headroom learn --verbosity can also learn your conciseness preferences from past sessions.

5. Quick Start

5.1 Installation

1
2
3
4
5

# Python (includes the headroom CLI)
pip install "headroom-ai[all]"

# TypeScript SDK (library mode, no CLI)
npm install headroom-ai

Requires Python 3.10+. [all] covers the core stack; framework adapters (LangChain, Agno, etc.) need their extras installed separately.

5.2 Three Ways to Integrate

Option A: Wrap Agent (least effort)

1
2
3
4

headroom wrap claude          # Claude Code
headroom wrap codex           # Codex CLI
headroom wrap copilot         # Copilot CLI
headroom wrap opencode        # OpenCode

One command starts the proxy and rewrites the agent configuration. To undo: headroom unwrap claude.

Option B: Proxy (zero code changes)

1
2
3
4
5

headroom proxy --port 8787

# In another terminal, point the base URL at the proxy
ANTHROPIC_BASE_URL=http://localhost:8787 claude
# or OPENAI_BASE_URL=http://localhost:8787/v1

Any OpenAI-compatible client works. For Cursor you need to change the API Base URL manually in settings.

Option C: Inline SDK

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

TypeScript: import { compress } from 'headroom-ai'.

5.3 Verifying and Viewing the Savings

1
2
3
4

headroom doctor              # health check, confirm routing works
headroom perf                # view compression statistics
headroom dashboard           # real-time savings dashboard (requires the proxy running)
curl http://localhost:8787/stats

5.4 MCP Integration

1

headroom mcp install

Exposes three MCP tools for any MCP client to use.

6. MCP Tool Reference

Typical flow: after tool output is compressed, the response carries a __headroom_hash; when the agent needs more detail it calls headroom_retrieve.

7. Usage Advice

1. Turn it on first for tool-output-heavy scenarios: JSON API responses, metrics, build logs, and multi-tool agent sessions benefit most
2. Passing code through by default is reasonable: do not force compression of function bodies; an agent reading code needs the full logic anyway
3. Trust CCR: if the agent cannot answer completely after compression, it will retrieve automatically; there is no need to disable compression just to be safe
4. Use proxy / wrap for long sessions: the cumulative effect is far more pronounced than in a single conversation
5. Turn on memory for cross-agent collaboration: Claude and Codex can share a SharedContext to avoid duplicate context
6. Use headroom learn to mine failed sessions: it automatically writes lessons learned into CLAUDE.local.md / AGENTS.md

A few design principles worth knowing:

• Local-first: compression, caching, and retrieve all happen locally; prompt contents are not uploaded by default
• Determinism over LLM summarization: no LLM is used to do the compression, avoiding hallucination and extra API cost
• Reversible over truncation: CCR means aggressive compression carries no risk of information loss
• Cache-friendly: the Live zone + CacheAligner design does not break the provider’s KV cache

8. Common CLI Commands

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

headroom wrap <agent>       # wrap an agent (claude/codex/copilot/...)
headroom unwrap <agent>     # undo the wrapping
headroom proxy --port 8787  # start the proxy
headroom doctor             # health check
headroom perf               # compression performance report
headroom dashboard          # real-time dashboard
headroom learn              # mine failed sessions and write corrections
headroom learn --verbosity  # learn conciseness preferences
headroom output-savings     # estimate output token savings
headroom update             # check for and apply upgrades
headroom mcp install        # install the MCP configuration

9. Relationship to CodeGraph

Headroom and CodeGraph address different sides of the agent context problem and can be stacked:

One handles “navigation,” the other handles “lightening the load” — they complement each other on the same agent pipeline.

10. Summary

Headroom turns an AI coding assistant from “paying full price for redundant tool output” into “reading a compressed summary first and fetching the original only when needed.”

• Comparison: without Headroom, tool output enters the context as-is (60k+ tokens in the SRE scenario); with Headroom, compression is usually 60%–92%, with accuracy benchmarks essentially on par
• Principle: ContentRouter routes by type → SmartCrusher / CodeCompressor / Kompress deterministic compression → CCR caches the original text for retrieval
• Usage: install headroom-ai → headroom wrap claude or headroom proxy → verify with headroom doctor

If you already write code with Cursor or Claude Code and tool output often dominates your agent sessions, spending a minute on the wrap flow will usually show you clear token savings over long conversations.