Headroom: Compress LLM Inputs by 60-95% — A Token-Saving Proxy, Library & MCP Server — A Practical Guide 2026 #

┌──────────────────────────────────────────────────────┐
│              Headroom Compression Pipeline            │
│                                                      │
│  ┌────────────┐  ┌─────────────┐  ┌──────────────┐  │
│  │  Tool Output│  │  Log Files  │  │  RAG Chunks  │  │
│  │  (JSON)    │  │  (.log)     │  │  (embeddings)│  │
│  └─────┬──────┘  └──────┬──────┘  └──────┬───────┘  │
│        │                │                 │          │
│        ▼                ▼                 ▼          │
│  ┌───────────────────────────────────────────────┐   │
│  │          Headroom Compressor Engine            │   │
│  │  • Deduplication  • Summarization             │   │
│  │  • Pruning        • Format optimization       │   │
│  └──────────────────────────┬────────────────────┘   │
│                             │ 60-95% fewer tokens    │
│  ┌──────────────────────────▼────────────────────┐   │
│  │              LLM API Call                      │   │
│  │  (Claude Code / Codex / Copilot / Gemini CLI)  │   │
│  └───────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────┘

Headroom pipeline: input → compress → LLM with 60-95% fewer tokens

Introduction #

If you’re paying for LLM API calls in 2026, you’re probably burning 40-70% of your token budget on redundant context: duplicate tool outputs, verbose log files, and bloated RAG chunks that the LLM reads but never uses. Headroom (19,745 GitHub stars) is the open-source tool that sits between your AI agent and the LLM, compressing inputs by 60-95% while preserving answer quality. It ships as a Python library, a CLI proxy, and an MCP server — compatible with Claude Code, Codex CLI, Copilot, Gemini CLI, and any OpenAI-compatible API. Single dependency, 10 lines to integrate, and real benchmarks show the same answers with fraction of the cost.

What Is Headroom? #

Headroom is a token compression layer for LLM pipelines that reduces input token counts before they reach the model. It is not a summarization tool — it is a structural optimizer. It understands the difference between “important signal” and “noisy context” in tool outputs, logs, files, and retrieval-augmented chunks.

Key capabilities:

• Input compression — Deduplicate, prune, and summarize tool outputs before LLM consumption
• Multi-format support — Handles JSON, logs, markdown, code files, and RAG embeddings
• 3 deployment modes — Python library, CLI proxy, and MCP server
• Model-agnostic — Works with Claude, GPT-4o, Gemini, and any OpenAI-compatible endpoint
• Quality-preserving — Benchmarked to produce equivalent answers at 60-95% token reduction
• Zero-config start — Ships with sensible defaults; optimize later with custom rules

The project is built with Python, uses minimal dependencies (just tiktoken for token counting), and integrates via standard HTTP APIs. It stores compression state in memory or Redis for multi-session scenarios.

How Headroom Works #

Headroom operates through a three-stage pipeline:

Stage 1: Input Ingestion #

# Install the library
pip install "headroom-ai[all]"

# Basic compression of a tool output
python -c "
import headroom
result = headroom.compress('''
[Very long JSON output from a tool call... 5000 tokens]
''')
print(f'Original: {result.original_tokens} tokens')
print(f'Compressed: {result.compressed_tokens} tokens')
print(f'Savings: {result.savings_pct}%')
"

Stage 2: Compression Engine #

The compression engine applies multiple strategies:

# Custom compression rules
from headroom import Compressor

compressor = Compressor(
    strategy="balanced",  # "aggressive" | "balanced" | "conservative"
    max_reduction_pct=95,
    min_quality_score=0.85,
    dedup_threshold=0.9,
    summary_length_ratio=0.3,
)

# Apply to mixed inputs
compressed = compressor.compress([
    {"type": "tool_output", "data": tool_result_json},
    {"type": "log_file", "data": log_content},
    {"type": "rag_chunk", "data": embedded_text},
    {"type": "code_file", "data": source_code},
])

Stage 3: LLM Integration #

# Start the proxy server
headroom serve --port 8787 --compressor balanced

# Point your AI agent to the proxy instead of the LLM directly
# Agent -> Headroom Proxy (8787) -> Compressed -> LLM API

// .env — Configure which LLM to proxy through
HEADROOM_PROXY_PORT=8787
LLM_ENDPOINT=https://api.anthropic.com/v1/messages
LLM_MODEL=claude-sonnet-4-20250514
LLM_API_KEY=${ANTHROPIC_API_KEY}
COMPRESSION_STRATEGY=balanced

Installation & Setup #

Quick Start (Library Mode) #

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

# One-line compression
python -c "
import headroom
compressed = headroom.compress(your_long_input)
print(compressed.text)
"

Node.js Setup #

# Install
npm install headroom-ai

Proxy Mode (Recommended for AI Agents) #

# Install and start
pip install "headroom-ai[all]"
headroom serve --host 0.0.0.0 --port 8787

# Test compression
curl -X POST http://localhost:8787/compress \
  -H "Content-Type: application/json" \
  -d '{"input": "Very long context..."}' | jq

# Expected response:
# {
#   "original_tokens": 4523,
#   "compressed_tokens": 891,
#   "savings_pct": 80.3,
#   "compressed_text": "..."
# }

MCP Server Mode #

# Start as MCP server
headroom mcp-serve --port 9090

# Connect from Claude Code
claude-code --mcp http://localhost:9090

# The MCP server exposes:
# - headroom/compress — Compress text input
# - headroom/benchmark — Run compression benchmark
# - headroom/config — Get/update compression settings

Advanced Usage / Production Hardening #

Context-Aware Compression #

Headroom adapts its compression strategy based on the input type. Code-heavy inputs retain more structure, while verbose log files get aggressive pruning.

# Context-aware compression example
from headroom import ContextCompressor

ctx_compressor = ContextCompressor(
    code_preserve=0.9,    # Keep 90% of code structure
    log_prune=0.95,       # Prune 95% of repetitive log lines
    json_dedup=0.9,       # Deduplicate similar JSON fields
)

# Auto-detect input type and apply best strategy
result = ctx_compressor.compress(input_data)
print(f"Type detected: {result.input_type}")
print(f"Savings: {result.savings_pct}%")

Token Accounting Dashboard #

Track your savings in real-time when running the proxy server in dashboard mode.

# Start proxy with built-in monitoring dashboard
headroom serve --port 8787 --dashboard --dashboard-port 3000

# View dashboard at http://localhost:3000
# See real-time token savings, compression ratios, and cost tracking

Integration with Claude Code, Codex CLI, Copilot, and Gemini CLI #

Headroom works with any agent that sends HTTP requests to an LLM API. Here’s how to integrate with popular tools:

Claude Code #

# Method 1: Use as MCP server
headroom mcp-serve --port 9090
# Then in Claude Code: add-mcp headroom http://localhost:9090

# Method 2: Set as API proxy in .claude-env
export CLAUDE_API_BASE_URL=http://localhost:8787/v1
# Claude Code automatically routes through Headroom

Codex CLI #

# Point Codex through Headroom proxy
export OPENAI_API_BASE=http://localhost:8787/v1
codex --model gpt-4o --prompt "Fix the auth bug"
# All context goes through Headroom compression first

OpenRouter Aggregation #

# Use Headroom with OpenRouter for multi-model cost savings
headroom serve \
  --proxy http://api.openrouter.ai/api/v1 \
  --model meta-llama/llama-3.1-405b \
  --compressor balanced

# Headroom compresses inputs, then sends to OpenRouter
# You pay for compressed tokens, not raw tokens

For self-hosted proxy infrastructure, HTStack DigitalOcean droplets provide stable low-latency connections. Consider WebShare data-center proxies for multi-region deployment. For token trading integrations, connect to Binance or OKX via headroom’s proxy layer.

Benchmarks / Real-World Use Cases #

Compression Benchmarks #

Testing on 100 real-world tool outputs (mix of terminal output, git diffs, file contents, and RAG chunks):

Cost Reduction: Real Scenario #

A developer using Claude Code for a 50K-line Python project:

# Before Headroom:
# Daily context: ~120,000 tokens/day
# Cost: ~$48/month (Claude Sonnet @ $3/M)

# After Headroom (balanced mode):
# Daily context: ~28,000 tokens/day
# Cost: ~$11/month
# Savings: ~$37/month = 77% reduction

RAG Chunk Compression #

Compressing retrieved documents before sending to LLM:

from headroom import Compressor, rag_compress

# Compress RAG chunks before LLM
compressed_chunks = rag_compress(
    retrieved_documents,
    min_relevance_score=0.7,
    max_chunks=10,
    strategy="balanced"
)

# Result: 47 original chunks → 12 compressed chunks
# Same answer quality, 74% fewer tokens

Real-World Use Case: CI/CD Log Analysis #

A team processes 500 GitHub Actions logs per week:

# Batch compress logs
headroom compress-batch \
  --input ./ci-logs/*.log \
  --output ./compressed-logs/ \
  --strategy conservative \
  --max-savings 70

# Analyze compressed logs with AI
cat ./compressed-logs/build-42.log | \
  headroom serve --prompt "Find the root cause of this failure"

Advanced Usage / Production Hardening #

Custom Compression Rules #

Define domain-specific compression rules:

# headroom-config.yaml
rules:
  # Skip compressing code files below a threshold
  - pattern: "\\.py$"
    min_compress_ratio: 0.5
  
  # Always preserve test files
  - pattern: "test_.*\\.py$"
    compress: false
  
  # Aggressive compression for CI logs
  - pattern: "ci-logs/"
    max_tokens: 500
    strategy: aggressive
  
  # Preserve API schemas
  - pattern: "openapi.*\\.yaml$"
    compress: false
    dedup: true

Redis-backed Session State #

For multi-session scenarios, persist compression state:

# Start with Redis state backend
headroom serve \
  --redis-url redis://localhost:6379/0 \
  --session-ttl 3600

# Session state persists across requests
# Useful for long-running agent sessions

Health Checks & Monitoring #

# Health check endpoint
curl -s http://localhost:8787/health | jq

# Compression statistics
curl -s http://localhost:8787/stats | jq
# {
#   "total_requests": 1247,
#   "total_tokens_saved": 892341,
#   "avg_savings_pct": 76.4,
#   "error_rate": 0.02
# }

# Rate limiting
curl -s http://localhost:8787/config | jq

Comparison with Alternatives #

Limitations / Honest Assessment #

Headroom is not a silver bullet. Here’s when it’s NOT a good fit:

1. Latency-sensitive applications — Compression adds 10-50ms per request. For ultra-low-latency use cases (sub-100ms total), the overhead may not be acceptable.

2. Extremely short inputs — For inputs under 500 tokens, compression overhead exceeds savings. Headroom is optimized for long-context scenarios (2,000+ tokens).

3. Quality-critical narrow tasks — If a 1% quality drop is unacceptable (e.g., legal document review), use conservative mode with 70% max savings instead of balanced.

4. Non-text inputs — Headroom compresses text only. Binary data, images, and audio require separate preprocessing.

5. Cost of deployment — Running the proxy server adds infrastructure complexity. For single-developer setups with low token usage, the library mode is sufficient.

Frequently Asked Questions #

Q: How does Headroom differ from a simple LLM summarizer?

A: Headroom uses structural analysis (token boundaries, format-aware deduplication, relevance scoring) rather than generative summarization. It preserves critical information structure (code syntax, JSON schema, API signatures) that summarizers might corrupt.

Q: Does Headroom work with local models like Ollama?

A: Yes. Point the proxy to any Ollama endpoint: LLM_ENDPOINT=http://localhost:11434/v1. Compression happens before the request reaches Ollama, reducing VRAM usage.

Q: Can I run Headroom on a VPS for team usage?

A: Yes. The library runs as a lightweight Python service. A basic VPS with 1 vCPU and 1GB RAM handles 50+ concurrent compression requests. For multi-session state persistence, add a Redis backend. Docker is not officially supported for headroom.

Q: Is there an API key or usage limit?

A: No. Headroom is open-source (MIT license), completely free, and has no usage limits. The only cost is the LLM API calls you make through the proxy.

Q: How does Headroom handle RAG retrieval?

A: Headroom includes a rag_compress function that scores, deduplicates, and prunes retrieved chunks before sending them to the LLM. It uses embedding similarity to preserve high-relevance chunks.

Sources & Further Reading #

• Official docs: https://github.com/chopratejas/headroom
• GitHub repository: https://github.com/chopratejas/headroom
• Compression benchmark methodology: https://github.com/chopratejas/headroom/blob/main/docs/BENCHMARKS.md
• MCP server documentation: https://github.com/chopratejas/headroom/blob/main/docs/MCP.md
• Community discussion: https://github.com/chopratejas/headroom/discussions

Conclusion: Slash Your LLM Token Costs by 60-95% — Run It in 10 Minutes #

Headroom is the missing infrastructure layer that every AI agent pipeline needs. Instead of paying for bloated context, you compress it before it reaches the model. The library gives you programmatic control, the proxy gives you zero-code integration, and the MCP server gives you seamless Claude Code compatibility.

Whether you’re a single developer trying to reduce Claude API bills, a team running AI-powered CI/CD, or building a production RAG system, Headroom delivers measurable cost savings without sacrificing answer quality.

Join the dibi8 English Telegram group to discuss Headroom configurations. Check out our guides on [本地ChatGPT](https://dibi8.com/nanochat-karpathy-100-chatg[AI Agent平台](https://dibi8.com/paperclip-open-source-agent-workplace-managing-ai-agents-at-scale)ibi8-internal-link) for complementary AI tooling. Try Headroom today — install it, point your proxy, and watch your token bills drop.

Some links above are affiliate links. dibi8.com may earn a commission if you sign up, at no extra cost to you. Helps keep the site running and the content free.