Headroom — Compress AI Agent Context by 60-95% Without Losing Accuracy

If you run Claude Code, Codex, Cursor, or any AI coding agent daily, you've seen the problem: tool outputs balloon to 50, 70, even 100K tokens per turn. You pay for every token, and worse — large prompts slow down reasoning and eat into your context window.

Headroom sits between your agent and the LLM provider and compresses everything the agent reads — tool outputs, logs, RAG chunks, files, conversation history — before it reaches the model. The result: 60-95% fewer tokens with the same answers. It runs entirely on your machine, requires zero code changes, and the originals are cached locally so the LLM can retrieve them if needed.

Created by Tejas Chopra and trending with over 42,000 GitHub stars since its January 2026 release, Headroom has become the go-to token-savings layer for the AI coding ecosystem.

Why It's Trending

• Massive cost savings — compresses 17K-token code search results to 1.4K (92% reduction) without losing accuracy on standard benchmarks.
• Zero-code setup — a single headroom wrap claude command intercepts your agent's traffic. No code changes needed.
• Multiple deployment modes — inline library, drop-in proxy, MCP server, or agent wrapper. Pick what fits your workflow.
• Reversible compression (CCR) — originals are cached locally. The LLM calls headroom_retrieve on demand if it needs the full context.
• Cross-agent memory — shared storage across Claude Code, Codex, Gemini, Cursor, and others with automatic deduplication.
• Output token reduction — also cuts what the model writes back (preambles, restated code, deep thinking on routine steps).
• Self-hosted — everything runs locally. Your data never leaves your machine.

Prerequisites

• Python 3.10+ (Python 3.11+ recommended)
• Any AI coding agent (Claude Code, Codex, Cursor, Aider, Copilot CLI, etc.)
• pip, pipx, or uv for installation
• Optional: a GPU for running the Kompress-v2-base model (fallback to CPU works fine)

How It Works

Headroom intercepts prompts on their way to the LLM and runs them through a compression pipeline:

The pipeline consists of several stages:

• ContentRouter — detects the content type (JSON, code, prose, logs) and selects the right compressor.
• SmartCrusher — universal JSON compressor: arrays of dicts, nested objects, mixed types.
• CodeCompressor — AST-aware compression for Python, JS, Go, Rust, Java, C++.
• Kompress-base — a HuggingFace model trained on agentic traces for text compression.
• CacheAligner — stabilizes prefixes so Anthropic/OpenAI KV caches actually hit their mark.
• CCR (Cached Compression Retrieval) — stores originals locally. The LLM calls headroom_retrieve if it needs the full context.

Installation

Python (pip)

pip install "headroom-ai[all]"

Python (pipx — isolated environment)

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

Node.js / TypeScript

npm install headroom-ai

Docker

docker pull ghcr.io/chopratejas/headroom:latest

Quick Start — Wrap Your Agent

The fastest way to try Headroom is with the headroom wrap command. It automatically intercepts your agent's HTTP traffic and routes it through the compression proxy:

# Install Headroom
pip install "headroom-ai[all]"

# Wrap Claude Code (works with Codex, Cursor, Aider, Copilot CLI too)
headroom wrap claude

# See your savings
headroom perf

That's it. Your Claude Code sessions now send compressed prompts to the LLM. No configuration files, no code changes, no environment variables to set.

Supported agents:

Agent	Command	Notes
Claude Code	headroom wrap claude	Supports --memory and --code-graph
Codex	headroom wrap codex	Shares memory with Claude
Cursor	headroom wrap cursor	Prints config — paste once
Aider	headroom wrap aider	Starts proxy + launches
Copilot CLI	headroom wrap copilot	Starts proxy + launches

Proxy Mode (Any Language, Any Framework)

If you want Headroom as a system-wide proxy without wrapping a specific agent:

headroom proxy --port 8787

Then configure your agent or application to point at http://localhost:8787. Headroom acts as an OpenAI-compatible proxy, so any tool that works with the OpenAI API works with Headroom transparently.

This is especially useful for:

• Multi-agent setups where several agents share the same compression layer
• Applications written in languages other than Python/TypeScript
• Teams that want a centralized compression gateway

Library Mode

For Python and TypeScript applications, Headroom can be used inline:

from headroom import compress

messages = [
    {"role": "user", "content": very_long_tool_output}
]

compressed = compress(messages, model="claude-sonnet-4-20250514")
print(f"Saved {compressed['stats']['tokens_saved_pct']:.1f}%")

For TypeScript:

import { compress } from "headroom-ai";

const compressed = await compress(messages, { model: "claude-sonnet-4-20250514" });
console.log(`Saved ${compressed.stats.tokens_saved_pct}%`);

MCP Server Mode

Headroom exposes its compression as MCP tools, making it available to any MCP-compatible client:

headroom mcp install

This registers three tools:

• headroom_compress — compress a prompt
• headroom_retrieve — retrieve the original from the CCR cache
• headroom_stats — view compression statistics

Output Token Reduction

Beyond compressing what you send to the LLM, Headroom can also cut what the model writes back:

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

This appends a "be terse" note to the system prompt and dials down thinking effort on routine turns (file reads, passing tests). New questions and errors keep full effort. The result is estimated at 30-40% reduction in output tokens on typical agent workloads.

Headroom can also learn your preferred verbosity from past sessions:

headroom learn --verbosity
headroom learn --verbosity --apply

headroom learn — Mine Failures, Improve Prompts

One of Headroom's most unique features is headroom learn. It scans past agent sessions, identifies failures (failed commands, hallucinated paths, repeated errors), and writes corrections directly to CLAUDE.md or AGENTS.md:

headroom learn

The learning process:

1. Scans session logs for failure patterns
2. Extracts the context around each failure
3. Generates corrective instructions
4. Appends them to your project's CLAUDE.md file

This creates a feedback loop where Headroom gets smarter about your codebase over time.

Performance Benchmarks

Savings on real agent workloads:

Workload	Before (tokens)	After (tokens)	Savings
Code search (100 results)	17,765	1,408	92%
SRE incident debugging	65,694	5,118	92%
GitHub issue triage	54,174	14,761	73%
Codebase exploration	78,502	41,254	47%

Accuracy preserved on standard benchmarks:

Benchmark	Category	Baseline	Headroom	Delta
GSM8K	Math	0.870	0.870	±0.000
TruthfulQA	Factual	0.530	0.560	+0.030
SQuAD v2	QA	—	97%	19% compression
BFCL	Tools	—	97%	32% compression

Configuration

Headroom reads environment variables for fine-grained control:

# Disable update checks
export HEADROOM_UPDATE_CHECK=off

# Enable output token reduction
export HEADROOM_OUTPUT_SHAPER=1

# Leave 10% of conversations unshaped as control group
export HEADROOM_OUTPUT_HOLDOUT=0.1

# Use a different context tool
export HEADROOM_CONTEXT_TOOL=lean-ctx

# Apple GPU offload for memory embedder
export HEADROOM_EMBEDDER_RUNTIME=pytorch_mps

Verification Checklist

After setting up Headroom, verify it's working:

• headroom status shows the proxy is running
• headroom perf reports compression ratios
• Your agent completes tasks normally (no errors, same quality)
• The proxy dashboard (if enabled) shows active compression
• headroom learn finds and reports failure patterns

Limitations

• Not for single-provider compaction — if you only use one provider's native compaction and don't need cross-agent memory, Headroom may be overkill.
• Requires a local process — won't work in sandboxed environments where local processes can't run.
• Output savings are estimates — Headroom can't measure what the model would have written without shaping, so output savings are reported with confidence intervals.

Compared to Alternatives

Feature	Headroom	RTK	lean-ctx	Compresr
Scope	All context — tools, RAG, logs, files	CLI outputs only	CLI commands, MCP tools	Text API
Local/self-hosted	Yes	Yes	Yes	No
Reversible (CCR)	Yes	No	No	No
Cross-agent memory	Yes	No	No	No
Output token reduction	Yes	No	No	No
Deployment modes	Proxy, library, MCP, wrap	CLI wrapper	CLI wrapper, MCP	API call

Resources

• GitHub: github.com/chopratejas/headroom
• Documentation: headroom-docs.vercel.app/docs
• PyPI: pypi.org/project/headroom-ai
• HuggingFace Model: huggingface.co/chopratejas/kompress-v2-base
• Discord: discord.gg/yRmaUNpsPJ
• License: Apache 2.0