Question 1

What is Headroom?

Accepted Answer

Headroom is an open-source context optimization layer for LLM tooling and AI agents. It compresses tool calls, database queries, file reads, and RAG retrievals by 40-90% before they reach the model, delivering the same answers at a fraction of the token cost.

Question 2

How does Headroom work?

Accepted Answer

Headroom uses three components: CacheAligner stabilizes message prefixes so provider KV cache hits (leveraging Claude's 90% read discount), ContentRouter auto-detects content type and routes to the optimal compressor (AST-aware for 6 languages), and IntelligentContext uses score-based token fitting with learned importance while storing originals for on-demand retrieval.

Question 3

How do I install Headroom?

Accepted Answer

Install via pip: pip install headroom-ai[all]. You can use it as a Python library with a single function call, as a transparent proxy with zero code changes (headroom proxy --port 8787), or wrap coding agents directly (headroom wrap claude).