Headroom

Compress everything your AI agent reads. Same answers, fraction of the tokens.

Every tool call, log line, DB read, RAG chunk, and file your agent injects into a prompt is mostly boilerplate. Headroom strips the noise and keeps the signal — losslessly, locally, and without touching accuracy.

100 logs. One FATAL error buried at position 67. Both runs found it. Baseline 10,144 tokens → Headroom 1,260 tokens — 87% fewer, identical answer. python examples/needle_in_haystack_test.py

Quick start

Works with Anthropic, OpenAI, Google, Bedrock, Vertex, Azure, OpenRouter, and 100+ models via LiteLLM.

Wrap your coding agent — one command:

pip install "headroom-ai[all]"

headroom wrap claude      # Claude Code
headroom wrap codex       # Codex
headroom wrap cursor      # Cursor
headroom wrap aider       # Aider
headroom wrap copilot     # GitHub Copilot CLI

Using pipx? Current release wheels are built for Python 3.10 through 3.13, so choose a supported interpreter explicitly:

pipx install --python python3.13 "headroom-ai[all]"

Drop it into your own code — Python or TypeScript:

from headroom import compress

result = compress(messages, model="claude-sonnet-4-5")
response = client.messages.create(model="claude-sonnet-4-5", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

import { compress } from 'headroom-ai';
const result = await compress(messages, { model: 'gpt-4o' });

Or run it as a proxy — zero code changes, any language:

headroom proxy --port 8787
ANTHROPIC_BASE_URL=http://localhost:8787 your-app
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

Why Headroom

• Accuracy-preserving. GSM8K 0.870 → 0.870 (±0.000). TruthfulQA +0.030. SQuAD v2 and BFCL both 97% accuracy after compression. Validated on public OSS benchmarks you can rerun yourself.
• Runs on your machine. No cloud API, no data egress. Compression latency is milliseconds — faster end-to-end for Sonnet / Opus / GPT-4 class models than a hosted service round-trip.
• Kompress-base on HuggingFace. Our open-source text compressor, fine-tuned on real agentic traces — tool outputs, logs, RAG chunks, code. Install with pip install "headroom-ai[ml]".
• Cross-agent memory and learning. Claude Code saves a fact, Codex reads it back. headroom learn mines failed sessions and writes corrections straight to CLAUDE.md / AGENTS.md / GEMINI.md — reliability compounds over time.
• Reversible (CCR). Compression is not deletion. The model can always call headroom_retrieve to pull the original bytes. Nothing is thrown away.

Bundles the RTK binary for shell-output rewriting — full attribution below.

How it fits

 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-base  (text, HF)     │
    │                                                     │
    │  Cross-agent memory  ·  headroom learn  ·  MCP      │
    └────────────────────────────────────────────────────┘
        │   compressed prompt  +  retrieval tool
        ▼
 LLM provider  (Anthropic · OpenAI · Bedrock · …)

→ Architecture · CCR reversible compression · Kompress-base model card

Canonical pipeline lifecycle

Headroom now exposes one stable request lifecycle across compress(), the SDK, and the proxy:

Setup → Pre-Start → Post-Start → Input Received → Input Cached → Input Routed → Input Compressed → Input Remembered → Pre-Send → Post-Send → Response Received

• Transforms still do the work: CacheAligner, ContentRouter, SmartCrusher, CodeCompressor, Kompress-base, IntelligentContext / RollingWindow.
• Pipeline extensions observe or customize those lifecycle stages via on_pipeline_event(...).
• Compression hooks still work and now sit alongside the canonical lifecycle instead of being the only extension seam.
• Proxy extensions remain the server/app integration seam for ASGI middleware, routes, and startup policy.

Provider slices

Provider and tool-specific behavior is being moved behind dedicated modules under headroom/providers/ so core orchestration stays focused on lifecycle, sequencing, and policy.

• CLI/tool slices: headroom/providers/claude, copilot, codex, openclaw
• Provider runtime slices: headroom/providers/claude, gemini, plus shared backend/runtime dispatch in headroom/providers/registry.py
• Core files stay orchestration-first: wrap.py, client.py, cli/proxy.py, and proxy/server.py now delegate provider-specific env shaping, API target normalization, backend selection, and transport dispatch instead of inlining those rules.

Proof

Savings on real agent workloads:

Accuracy preserved on standard benchmarks:

Reproduce:

python -m headroom.evals suite --tier 1

Community, live:

→ Full benchmarks & methodology

Built for coding agents

MCP-native too — headroom mcp install exposes headroom_compress, headroom_retrieve, and headroom_stats to any MCP client.

Integrations

• SmartCrusher — universal JSON: arrays of dicts, nested objects, mixed types.
• CodeCompressor — AST-aware for Python, JS, Go, Rust, Java, C++.
• Kompress-base — our HuggingFace model, trained on agentic traces.
• Image compression — 40–90% reduction via trained ML router.
• CacheAligner — stabilizes prefixes so Anthropic/OpenAI KV caches actually hit.
• IntelligentContext — score-based context fitting with learned importance.
• CCR — reversible compression; LLM retrieves originals on demand.
• Cross-agent memory — shared store, agent provenance, auto-dedup.
• SharedContext — compressed context passing across multi-agent workflows.
• headroom learn — plugin-based failure mining for Claude, Codex, Gemini.

Install

pip install "headroom-ai[all]"          # Python, everything
npm  install headroom-ai                # TypeScript / Node
docker pull ghcr.io/chopratejas/headroom:latest

Granular extras: [proxy], [mcp], [ml] (Kompress-base), [agno], [langchain], [evals]. Requires Python 3.10+.

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

Documentation

Compared to

Headroom runs locally, covers every content type (not just CLI or text), works with every major framework, and is reversible.

Attribution. Headroom ships with the excellent RTK binary for shell-output rewriting — git show → git show --short, noisy ls → scoped, chatty installers → summarized. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it.

Contributing

git clone https://github.com/chopratejas/headroom.git && cd headroom
pip install -e ".[dev]" && pytest

Devcontainers in .devcontainer/ (default + memory-stack with Qdrant & Neo4j). See CONTRIBUTING.md.

Community

• Live leaderboard — 60B+ tokens saved and counting.
• Discord — questions, feedback, war stories.
• Kompress-base on HuggingFace — the model behind our text compression.

License

Apache 2.0 — see LICENSE.