What it is, installation, configuration, and DeepSeek V4 Pro / Open Code integration
Table of Contents
- What Is Headroom?
- Installation (Proxy Mode Recommended)
- Integrating With AI Tools
- Using It With DeepSeek V4 Pro + Open Code
- Other Ways to Use Headroom
- Useful Commands and Tips
- Troubleshooting
- References and Key Links
1. What Is Headroom?
Headroomis an open-source project that intelligently compresses the massive context (code, logs, search results, and more) exchanged with AI agents — particularly AI coding models —cutting cost by up to 95% while preserving response quality.
Developed by Netflix senior engineer Tejas Chopra, open-sourced in January 2026 under the Apache 2.0 license.
Why Is It Needed?
Every time an AI performs a task, a huge volume of context gets sent with each request:
- Code search results
- Log files
- API responses
- Prior conversation history
This drives up costand causesinformation overload, leading the AI to miss important details.
How It Works
[AI Agent] ──request──▶ [Headroom Proxy] ──compressed request──▶ [LLM API]
│
Smart compression
(removes repetition/noise)
Applies CacheAligner
| Stage | Description |
|---|---|
| Request interception | Sits between the AI agent and the API, intercepting every request |
| Smart compression | Replaces or compresses repetitive or less important information with reference links |
| Cache alignment | CacheAligner technology solves prompt-cache-busting issues to maximize cost savings |
Key Compression Engines
| Engine | Role |
|---|---|
SmartCrusher |
Generic JSON array / nested object compression |
CodeCompressor |
AST-aware compression for Python, JS, Go, Rust, Java, C++ |
Kompress-base |
HuggingFace-trained model for compressing agent traces |
CacheAligner |
Stabilizes Anthropic/OpenAI KV cache prefixes |
IntelligentContext |
Importance-score-based context fitting |
CCR |
Reversible compression (the LLM can retrieve the original if needed) |
Key Results
| Metric | Savings |
|---|---|
| Token reduction | 60% – 95% |
| Cost reduction | Up to ~50% (roughly 2x usage for the same budget) |
| Quality | Equal or slightly improved |
2. Installation (Proxy Mode Recommended)
Proxy mode is the simplest way to use Headroom without changing any existing code. It works with any LLM and tool, including DeepSeek V4 Pro and Open Code.
2.1 Installing Headroom
pip install "headroom-ai[proxy]"
For the full feature set:
pip install "headroom-ai[all]"
2.2 Running the Proxy Server
headroom proxy --port 8787
--port 8787: sets the port used by the proxy server (any other port works too)- On successful startup, you'll see
Listening on http://localhost:8787
2.3 Verifying It's Working
curl http://localhost:8787/health
Successful response:
{"status": "healthy", "version": "x.x.x"}
3. Integrating With AI Tools (Proxy Mode)
With the proxy server running, configure each AI tool to call its API through this proxy.
The Basic Principle
| Compatibility mode | Environment variable |
|---|---|
| OpenAI-compatible tools | OPENAI_BASE_URL=http://localhost:8787/v1 |
| Anthropic-compatible tools | ANTHROPIC_BASE_URL=http://localhost:8787 |
Integration Examples by Tool
| Tool | Command |
|---|---|
| Open Code (OpenClaude) | OPENAI_BASE_URL=http://localhost:8787/v1 openclaude |
| DeepSeek V4 Pro | OPENAI_BASE_URL=http://localhost:8787/v1 deepseek |
| Cursor | OPENAI_BASE_URL=http://localhost:8787/v1 cursor |
| Claude Code | ANTHROPIC_BASE_URL=http://localhost:8787 claude |
| Codex CLI | OPENAI_BASE_URL=http://localhost:8787/v1 codex |
| Aider | OPENAI_BASE_URL=http://localhost:8787/v1 aider |
| Copilot CLI | OPENAI_BASE_URL=http://localhost:8787/v1 copilot |
| Continue | Add OPENAI_BASE_URL=http://localhost:8787/v1 to the config file |
Tip for a permanent setup: add the following line to
~/.bashrcor~/.zshrcexport OPENAI_BASE_URL=http://localhost:8787/v1
4. Using It With DeepSeek V4 Pro + Open Code
Step-by-Step
Step 1: Run the Headroom proxy
headroom proxy --port 8787
Step 2: Run Open Code through the proxy
OPENAI_BASE_URL=http://localhost:8787/v1 openclaude
If calling DeepSeek V4 Pro directly:
OPENAI_BASE_URL=http://localhost:8787/v1 deepseek-v4-pro --model deepseek-v4-pro
Step 3: Verify it's working
- Type a normal coding question into Open Code
- The Headroom proxy terminal will display compression stats (tokens reduced)
- Use
headroom statsto check cumulative savings
✅ Compatibility guaranteed: Since Headroom operates at the proxy level, it never interferes with DeepSeek V4 Pro's specific API format or Open Code's communication protocol.
5. Other Ways to Use Headroom
5.1 Agent Wrap — the Easiest Option
headroom wrap openclaude
headroom wrap cursor
After this, Headroom is automatically applied whenever you run openclaude.
Quick win:
pip install "headroom-ai[all]", thenheadroom wrap claude
5.2 MCP Server (Model Context Protocol)
This method is efficient if you use multiple MCP clients.
headroom mcp install
Available MCP tools:
| Tool | Description |
|---|---|
headroom_compress |
Request text compression |
headroom_retrieve |
Retrieve compressed context |
headroom_stats |
View statistics |
5.3 Python Library
from headroom import compress
compressed = compress(
text="Very long log file contents...",
model="deepseek-v4-pro" # model can be specified
)
5.4 Multi-Agent Environments
If you're running Claude and Codex in parallel, you can share a common compressed context store with automatic deduplication via SharedContext.
6. Useful Commands and Tips
| Command | Description |
|---|---|
headroom stats |
Prints token/cost savings stats accumulated so far |
headroom reset |
Resets statistics |
headroom proxy --help |
Shows all proxy options |
headroom config |
Edit the config file (adjust compression level, etc.) |
Adjusting Compression Level (config.yaml)
compression:
level: "balanced" # "aggressive" | "balanced" | "conservative"
cache_alignment: true
Quick Start (One-Liner)
# Install + run the proxy
pip install "headroom-ai[proxy]" && headroom proxy --port 8787
# In another terminal
OPENAI_BASE_URL=http://localhost:8787/v1 openclaude
7. Troubleshooting
Q: The proxy server won't start.
- Check for a port conflict:
lsof -i :8787-> if occupied, switch to another port with--port 8788, etc. - Reinstall Headroom:
pip install --upgrade "headroom-ai[proxy]"
Q: My tool shows a "Connection refused" error.
- Verify the proxy server is running first
- Check that the port number in the environment variable matches (
http://localhost:8787)
Q: A specific DeepSeek V4 Pro parameter isn't working.
- Headroom passes parameters through unconditionally, so it's likely an issue with the tool itself
- Test without Headroom first, then compare
Q: I'm barely seeing any savings.
- Check the actual compression rate with
headroom stats - If the context is already small, compression gains may be minimal
8. References and Key Links
Official Resources
| Resource | URL |
|---|---|
| Official homepage | headroomlabs.ai |
| GitHub repository | github.com/chopratejas/headroom |
| Official docs (docs/) | github.com/chopratejas/headroom/tree/main/docs |
| PyPI package | pypi.org/project/headroom-ai |
Integration Guides (Official Docs)
| Guide | URL |
|---|---|
| LangChain integration | docs/langchain.md |
| CCR (reversible compression) guide | docs/ccr.md |
| Metrics & Monitoring | docs/metrics.md |
Reference Articles
| Title | URL |
|---|---|
| Building Cost-Efficient Agents with Headroom (Medium) | subratpati.medium.com |
| Headroom: Cut LLM Token Usage by Up to 95% (DEV.to) | dev.to/arshtechpro |
| A Practical Guide to Headroom Token Compression (Build This Now) | buildthisnow.com |
Related Technical Background
| Resource | Description |
|---|---|
| Phil Schmid — Context Engineering Principles | The foundation of Headroom's philosophy: the priority order "Raw > Compaction > Summarization" |
| Anthropic Prompt Caching Docs | Background for understanding CacheAligner |
| OpenAI Compatible API Spec | The basis for proxy-mode BASE_URL integration |
Version info: This document is based on Headroom v0.22 (as of June 2026). Apache 2.0 License | Developer: Tejas Chopra (Netflix Senior Engineer)