Headroom

The Context Optimization Layer for LLM Applications

Cut your LLM costs by 50-90% without losing accuracy

---

What It Does

Headroom is a smart compression proxy for LLM applications:

• Compresses tool outputs — 1000 search results → 15 items (keeps errors, anomalies, relevant items)
• Enables provider caching — Stabilizes prefixes so cache hits actually happen
• Manages context windows — Prevents token limit failures without breaking tool calls
• Reversible compression — LLM can retrieve original data if needed (CCR architecture)

Zero code changes required — point your existing tools at the proxy.

---

30-Second Quickstart

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

# Start proxy
headroom proxy --port 8787

# Verify
curl http://localhost:8787/health

Use with your tools:

# Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# Cursor / Continue / any OpenAI client
OPENAI_BASE_URL=http://localhost:8787/v1 cursor

# Python scripts
export OPENAI_BASE_URL=http://localhost:8787/v1
python your_script.py

That's it. You're saving tokens.

---

Verify It's Working

curl http://localhost:8787/stats

{
  "tokens": {"saved": 12500, "savings_percent": 25.0},
  "cost": {"total_savings_usd": 0.04}
}

---

Installation

pip install "headroom-ai[proxy]"     # Proxy server (recommended)
pip install headroom-ai              # SDK only
pip install "headroom-ai[code]"      # AST-based code compression
pip install "headroom-ai[llmlingua]" # ML-based compression
pip install "headroom-ai[all]"       # Everything

Requirements: Python 3.10+

---

Features

Feature	Description	Docs
SmartCrusher	Compresses JSON tool outputs statistically	Transforms
CacheAligner	Stabilizes prefixes for provider caching	Transforms
RollingWindow	Manages context limits without breaking tools	Transforms
CCR	Reversible compression with automatic retrieval	CCR Guide
Text Utilities	Opt-in compression for search/logs	Text Compression
LLMLingua-2	ML-based 20x compression (opt-in)	LLMLingua
Code-Aware	AST-based code compression (tree-sitter)	Transforms
ContentRouter	Auto-routes content to optimal compressor	Transforms

---

Providers

Provider	Token Counting	Cache Optimization
OpenAI	tiktoken (exact)	Automatic prefix caching
Anthropic	Official API	cache_control blocks
Google	Official API	Context caching
Cohere	Official API	-
Mistral	Official tokenizer	-

New models auto-supported — Unknown models get sensible defaults based on naming patterns (e.g., claude-opus-* gets Opus pricing). Custom limits via ~/.headroom/models.json or HEADROOM_MODEL_LIMITS env var.

---

Performance

Scenario	Before	After	Savings
Search results (1000 items)	45,000 tokens	4,500 tokens	90%
Log analysis (500 entries)	22,000 tokens	3,300 tokens	85%
Long conversation (50 turns)	80,000 tokens	32,000 tokens	60%

Overhead: ~1-5ms per request.

---

Safety

• Never removes human content — User/assistant messages are never compressed
• Never breaks tool ordering — Tool calls and responses stay paired
• Parse failures are no-ops — Malformed content passes through unchanged
• Compression is reversible — LLM can retrieve original data via CCR

---

Documentation

Guide	Description
SDK Guide	Wrap your client for fine-grained control
Proxy Guide	Production deployment
Configuration	All configuration options
CCR Guide	Reversible compression architecture
Metrics	Monitoring and observability
Troubleshooting	Common issues
Architecture	How it works internally

---

Examples

See examples/ for runnable code:

• basic_usage.py — Simple SDK usage
• proxy_integration.py — Using with different clients
• ccr_demo.py — CCR architecture demonstration

---

Contributing

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

See CONTRIBUTING.md for details.

---

License

Apache License 2.0 — see LICENSE.

---

_{Built for the AI developer community}