Introduction

Headroom compresses everything your AI agent reads -- tool outputs, database results, file reads, RAG retrievals, API responses -- before it reaches the LLM. The model sees less noise, responds faster, and costs less.

Quick preview

import { compress } from 'headroom-ai';

const messages = [
  { role: 'user' as const, content: 'Analyze these results' },
];

const result = await compress(messages, { model: 'gpt-4o' });
// compressionRatio is tokensAfter / tokensBefore, so savings is 1 - ratio.
console.log(`Saved ${result.tokensSaved} tokens (${((1 - result.compressionRatio) * 100).toFixed(0)}%)`);

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

What gets compressed

Savings depend heavily on how repetitive the content is -- see Benchmarks and the reproducible scenario table below for measured numbers on real workloads.

Where Headroom fits

Your Agent / App
    |
    |  tool outputs, logs, DB reads, RAG results, file reads, API responses
    v
 Headroom  <-- proxy, Python library, TS SDK, or framework integration
    |
    v
 LLM Provider  (OpenAI, Anthropic, Google, Bedrock, 100+ via LiteLLM)

Headroom works as a transparent proxy (zero code changes), a Python function (compress()), a TypeScript function (compress()), or a framework integration (LangChain, Agno, Strands, LiteLLM, Vercel AI SDK, MCP).

Real-world results

Headroom is built for the scenario that matters most in agent workflows: a single critical error or fact buried inside a large, mostly-routine tool output. SmartCrusher preserves error items, anomalies (values outside normal statistical range), and first/last boundaries by construction -- not by keyword matching, but by statistical analysis of field variance -- so the signal survives even when the surrounding noise is compressed away aggressively.

Measured on local, seeded test data built from real MCP server output formats. These are not production telemetry, and they are reproducible:

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

Token counts are from the gpt-5.6 tokenizer. The corpus is generated, so the exact before/after counts move slightly with the seed; the savings hold across seeds (Code search 21%, SRE 56--57%, triage 29--30%, exploration 41--50% over five seeds). Savings depend on how repetitive your tool output is, so treat these as a shape, not a promise.

See Benchmarks for the wider suite.

Key Features

ctx = SharedContext()
ctx.put("research", big_output)
summary = ctx.get("research")

Framework Integrations

from headroom.integrations.langchain import HeadroomChatModel
llm = HeadroomChatModel(ChatOpenAI())

from headroom.integrations.agno import HeadroomAgnoModel
model = HeadroomAgnoModel(Claude())
agent = Agent(model=model)

from headroom.integrations.strands import HeadroomStrandsModel
model = HeadroomStrandsModel(...)
agent = Agent(model=model)

headroom mcp install && claude

npm install headroom-ai

import { withHeadroom } from 'headroom-ai/vercel-ai'
const model = withHeadroom(openai('gpt-4o'))

Nothing is lost

Compressed content goes into the CCR store (Compress-Cache-Retrieve). The LLM gets a headroom_retrieve tool and can fetch full originals when it needs more detail. Compression is aggressive but reversible.

Next steps