Imagine!!!

You send 10,000 tokens to your AI. It uses 1,200 to answer. You paid for 8,800 tokens that did absolutely nothing. Netflix engineer Tejas Chopra built Headroom, a free, open-source tool that compresses the noise before it reaches the model. Same answer. 88% fewer tokens. Zero code changes.39,000 GitHub stars in 5 months.

Here's how to start using Headroom to reduce your AI token cost today.

You've Been Paying for Tokens That Do Nothing

Let me show you something that will make you immediately understand why this matters.

Your AI agent is debugging a production issue. It reads a log file. The log file is 10,000 lines long.

Here is what is actually in those 10,000 lines:

2026-07-22 10:00:01 INFO GET /api/users 200 45ms 2026-07-22 10:00:02 INFO GET /api/tasks 200 32ms 2026-07-22 10:00:03 INFO POST /api/tasks 201 67ms ... [9,946 more lines exactly like this] 2026-07-22 14:23:45 FATAL OutOfMemoryError at TaskService.java:234 ... [50 lines of actual error detail] 2026-07-22 14:23:46 INFO GET /api/health 200 5ms

Your AI reads every single line. It finds the FATAL error. It answers your question correctly.

You pay for 10,000 tokens.

But the AI only needed 1,200 of them. The other 8,800 were noise, repeated INFO lines saying nothing new, boilerplate that added nothing to the answer.

You just paid for 8,800 tokens that did absolutely nothing.

Multiply that by every log file, every code search, every database query, every RAG retrieval your AI agent makes in a day. A week. A month.

That is the problem. A Netflix engineer got tired of it and built the fix.

What Is Headroom In One Sentence

Headroom sits between your AI agent and the LLM, strips out the noise before it hits the model, and gives the model only what it actually needs.

Same answer. Fraction of the tokens. Fraction of the cost.

A 10,144-token log goes into Headroom and comes out at 1,260 tokens. The model finds the same FATAL error. You paid for 88% fewer tokens.

Not a demo trick. Not a one-time thing. That is what it does on every log file, every code search, every RAG retrieval — with zero changes to how the model thinks or answers.

Who Built This and Why

Tejas Chopra is a senior engineer at Netflix. Netflix runs AI agents at a scale that makes most organisations wince, and at that scale, every wasted token is real money.

Chopra estimates that as much as 90% of tokens sent to LLMs in agentic workflows are redundant, they add nothing to the final answer.

Think about that. 90%. Nine out of every ten tokens your agent sends contribute nothing to the response.

He released Headroom under the Apache 2.0 licence in January 2026, completely free, completely open source.

In five months it crossed 39,000 GitHub stars. It has collectively saved users roughly $700,000 and freed around 200 billion tokens.

Engineers found it, tried it, and told other engineers about it. That is the only reason it spread that fast.

If You Are New to AI: What "Tokens" Actually Means

Already know? Skip ahead. If not, this is the section that will make everything click.

Tokens are how AI models charge you. Every piece of text you send to an AI, and every response the AI generates, gets broken into small units called tokens. One token is roughly 4 characters. The word "hello" is one token. A paragraph is 50–100 tokens. A 10,000-line log file is 10,000+ tokens.

You pay per token. More tokens sent = higher bill.

Here is where it gets expensive: AI agents do not just send your question to the model. They send your question plus all the context they gathered, log files, search results, database responses, documentation. All of it goes in the same request. All of it gets billed.

A 10,000-token log file costs the same whether 9,800 of those tokens were noise or not.

Headroom removes the noise before it gets sent. The model gets a clean, compressed version. You pay for only what the model actually needed.

No AI knowledge required to use it. No code changes required. One command.

What Headroom Actually Is

Headroom is an open-source context compression layer that intelligently compresses everything an AI agent reads before it reaches the model, delivering 60–95% fewer tokens with zero accuracy regression.

Tejas Chopra released Headroom under the Apache 2.0 license in January 2026.

The tool sits between your agent and the LLM. When your agent produces a tool output, a log file, a code search result, a database response, a RAG chunk, Headroom intercepts it, compresses it, and sends the compressed version to the model. The model never sees the noise. It only sees the signal.

The compression is:

• Local:runs entirely on your machine. Your code, logs, and internal data never leave your infrastructure
• Reversible:the original content is cached locally. If the model needs the full text, it can retrieve it on demand
• Accurate:benchmarks show no meaningful degradation on GSM8K, TruthfulQA, or SQuAD v2
• Zero code change:the proxy mode requires no application changes at all

The Real Benchmark Numbers

The official measured results from Headroom's benchmarks:

| Use Case | Original Tokens | Compressed Tokens | Reduction |
|---|---|---|---|
| Code Search (100 results) | 17,765 | 1,408 | 92% |
| SRE Incident Troubleshooting | 65,694 | 5,118 | 92% |
| Log file analysis | 10,144 | 1,260 | 88% |
| JSON API response | High null/repeat density | — | 60–95% |
| Coding agent (general) | Baseline | — | 15–20% |

A tool-heavy agent run that previously consumed 65,694 tokens was reduced to just 5,118 tokens. Code search context shrank from 17.7K to 1.4K tokens. Netflix production workloads demonstrate 70–90% cost reduction with identical answers.

In a recent talk, Chopra estimated the tool had saved users roughly $700,000 and freed about 200 billion tokens collectively.

The pattern in every benchmark is consistent: the savings come from compressing non-prose payloads, not human-written prompts. The wins are largest in agentic and RAG pipelines where tool output dominates the context window.

Your carefully crafted system prompt compresses modestly. Your 10,000-line log file compresses by 88%.

Why the Compression Works: The Six Engines Under the Hood

Headroom is not a simple truncation tool. It does not just cut your content at 1,000 tokens and hope the important part was near the top.

It uses six compression engines, including AST-aware code reduction, JSON optimisation, and a HuggingFace-based text squasher, to eliminate redundant tokens while preserving the information the model actually needs.

Here is what each engine does:

Engine 1: JSON Compressor

Raw API responses and database query results are JSON. JSON is verbose by design, it is built for human readability and inter-system compatibility, not for token efficiency.

// Before Headroom — what your agent sends to the LLM: {"users": [{"id": "usr_001","email": "alice@example.com","first_name": "Alice","last_name": "Chen","phone": null,"address": null,"city": null,"country": null,"postal_code": null,"created_at": "2026-01-15T10:30:00Z","updated_at": "2026-07-01T09:00:00Z","last_login": "2026-07-22T08:45:00Z","subscription_tier": "free","is_verified": true,"is_active": true,"stripe_customer_id": null,"avatar_url": null},// ... 99 more users with the same structure] } // After Headroom — what the LLM actually receives: users[100]: id,email,first_name,last_name,created_at,last_login,subscription_tier usr_001,alice@example.com,Alice,Chen,2026-01-15,2026-07-22,free usr_002,bob@example.com,Bob,Smith,2026-02-10,2026-07-21,pro ... [98 more rows]
Null fields removed. Repeated field names collapsed to a header. Structure preserved, which means intact. Tokens: a fraction of the original.

Engine 2: Log Compressor

Log files are the most extreme case. A typical production log is 95% routine operational noise INFO: request received, DEBUG: cache hit, INFO: response sentrepeated thousands of times. The signal is the 5% that is WARN, ERROR, or FATAL.

// Before Headroom — 10,144 tokens of this: 2026-07-22 10:00:01 INFO Server started on port 3000 2026-07-22 10:00:01 INFO Database connected 2026-07-22 10:00:02 INFO GET /api/users 200 45ms 2026-07-22 10:00:02 INFO GET /api/tasks 200 32ms 2026-07-22 10:00:03 INFO POST /api/tasks 201 67ms ... [thousands of INFO lines] 2026-07-22 14:23:45 FATAL OutOfMemoryError: Java heap space at java.base/java.util.Arrays.copyOf(Arrays.java:3512) at com.example.TaskService.processBatch(TaskService.java:234) ... [stack trace] 2026-07-22 14:23:46 INFO GET /api/health 200 5ms ... [more INFO lines] // After Headroom — 1,260 tokens of this: [INFO lines: 10,091 total — compressed] [10:00:01] Server started, DB connected [10:00:02-14:23:44] Normal operation — 10,089 requests, all 200/201 [14:23:45 FATAL] OutOfMemoryError: Java heap space at TaskService.processBatch(TaskService.java:234) [full stack trace preserved] [14:23:46-onwards] Normal operation resumed

The FATAL error the thing the model needs is preserved in full. The 10,000 lines of noise are summarised in three lines. The model finds the same error. You pay for 88% fewer tokens.

Engine 3: AST-Aware Code Compressor

When your agent searches code, it often gets back full files when it needs specific functions. Headroom uses Abstract Syntax Tree parsing to strip irrelevant code structure while preserving the parts that matter for the query.

```

Full file returned by code search — 400 lines, 3,200 tokens

The model asked: "find the function that handles user authentication"

import os
import sys
import logging
from typing import Optional, Dict, List, Tuple
from datetime import datetime, timezone

... 20 more imports

DocumentService class - 150 lines

class DocumentService:def create_document(self, ...): ...
def update_document(self, ...): ...
def delete_document(self, ...): ...
# ... many more methods

EmailService class - 80 lines

class EmailService:def send_welcome_email(self, ...): ...
# ...

AuthService class - 60 lines

class AuthService:def authenticate_user(self, email: str, password: str) -> Optional[str]:"""Authenticate user and return JWT token"""
user = self.db.query(User).filter(User.email == email).first()if not user or not user.check_password(password):return Nonereturn self.generate_jwt(user.id)# ... more auth methods

After Headroom AST compression — 180 tokens:

File: src/services/auth.py — showing AuthService (query match)

class AuthService:def authenticate_user(self, email: str, password: str) -> Optional[str]:"""Authenticate user and return JWT token"""
user = self.db.query(User).filter(User.email == email).first()if not user or not user.check_password(password):return Nonereturn self.generate_jwt(user.id)# [+ 4 more methods — retrieve with headroom_retrieve if needed]

[DocumentService, EmailService: 230 lines — not shown — retrieve if needed]

```

Engine 4: RAG Chunk Deduplicator

RAG pipelines retrieve multiple chunks. Many share boilerplate, the same documentation header, the same copyright notice, the same introductory paragraph appearing in every chunk from the same source.

Headroom identifies and removes duplicate content across chunks before they reach the model, collapsing repeated boilerplate to a single reference.

Engine 5: Conversation History Compressor

Long agentic sessions accumulate conversation history. Earlier turns, especially tool outputs from steps the agent has already processed, can be compressed without losing the conclusions drawn from them.

Engine 6: ML-Based Text Compressor

For general text that does not fit neatly into the structured categories above, Headroom optionally uses a HuggingFace-based ML model (requires headroom-ai[ml]) to perform semantic compression, preserving meaning while reducing verbosity.

The Four Ways to Use Headroom

Headroom adapts to the existing flow in four modes, from the most transparent to the most granular.

Mode 1: Wrap (Easiest One Command, Zero Code Changes)

The wrap command intercepts an existing AI coding tool and compresses all context before it reaches the model. You do not change a single line of your application code.

```

Install

pip install "headroom-ai[all]"

Wrap Claude Code — all context compressed automatically

headroom wrap claude

Wrap Codex CLI

headroom wrap codex

Wrap Cursor

headroom wrap cursor

Wrap Aider

headroom wrap aider

Wrap GitHub Copilot CLI

headroom wrap copilot --subscription -- --model gpt-4o

Wrap OpenCode

headroom wrap opencode

Unwrap (remove Headroom from a tool)

headroom unwrap claude
```
From this point, every session with that tool runs through Headroom. Every tool output, log file, and RAG chunk is compressed before the model sees it. You do nothing else.

Mode 2: Proxy (Transparent Any Tool, Any Language)

The proxy mode starts a local HTTP server that acts as an OpenAI-compatible API endpoint. Point any tool at it instead of the real API endpoint. Everything that passes through gets compressed.

```

Start the Headroom proxy

headroom proxy --port 8787

With verbose logging to see compression happening in real time

headroom proxy --port 8787 --verbose
```
Now point your application at the proxy instead of the real API:

```

For tools that use environment variables:

export OPENAI_BASE_URL=http://127.0.0.1:8787
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787

Your existing application code — unchanged

python my_ai_agent.py
```

```

For applications that construct the client in code:

Before:

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

After (proxy mode):

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"],base_url="http://127.0.0.1:8787" # Route through Headroom
)

Everything else in your code stays identical

```

The proxy is the lowest-friction option for applications you do not own, third-party tools, legacy codebases, or any system where you cannot easily modify the API call.

Mode 3: Library (Most Control Inline in Your Code)

The library mode gives you direct access to the compression function in your Python or TypeScript code. Use this when you want control over exactly what gets compressed and when.

```
from headroom import compress
import anthropic
import os
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
def query_with_compression(messages: list, model: str) -> dict:"""
Compress messages before sending to Claude.
Measures and logs the token savings.
"""# Compress the messages
result = compress(messages, model=model)
# Log the savingsprint(f"Original tokens: {result.original_tokens}")print(f"Compressed tokens: {result.compressed_tokens}")print(f"Tokens saved: {result.tokens_saved}")print(f"Compression ratio: {result.compression_ratio:.1%}")
# Send compressed messages to Claude
response = client.messages.create(model=model,max_tokens=1000,messages=result.messages # Use compressed messages)
return {"content": response.content[0].text,"tokens_saved": result.tokens_saved,"compression_ratio": result.compression_ratio
}

Example: Processing a large log file

def analyse_log_file(log_content: str) -> str:"""Analyse a log file using compressed context"""
messages = [{"role": "user","content": f"Analyse this log and identify all errors:\n\n{log_content}"}]
result = query_with_compression(
messages,model="claude-opus-4-7-20250514")
print(f"\nSaved {result['tokens_saved']} tokens "f"({result['compression_ratio']:.0%} compression)")
return result["content"]

Read a large log file

with open("production.log", "r") as f:
log_content = f.read()
analysis = analyse_log_file(log_content)
print(f"\nAnalysis:\n{analysis}")
```

import { compress } from 'headroom-ai'; import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }); async function queryWithCompression(messages: Anthropic.MessageParam[],model: string ): Promise<{ content: string; tokensSaved: number }> { // Compress the messagesconst result = await compress(messages, { model }); console.log(`Original: ${result.originalTokens} tokens`); console.log(`Compressed: ${result.compressedTokens} tokens`); console.log(`Saved: ${result.tokensSaved} tokens (${ (result.compressionRatio * 100).toFixed(1) }%)`); // Send compressed messagesconst response = await client.messages.create({ model,max_tokens: 1000,messages: result.messages }); return {content: (response.content[0] as Anthropic.TextBlock).text,tokensSaved: result.tokensSaved }; } // Example usage async function analyseJsonResponse(apiResponse: object): Promise<string> {const messages: Anthropic.MessageParam[] = [{role: 'user',content: `Extract all user emails from this API response:\n\n${ JSON.stringify(apiResponse, null, 2) }`}]; const { content, tokensSaved } = await queryWithCompression( messages,'claude-opus-4-7-20250514'); console.log(`\nSaved ${tokensSaved} tokens on this call`);return content; }

LangChain integration:

```
from langchain_anthropic import ChatAnthropic
from headroom.langchain import HeadroomCallbackHandler

Drop-in integration with LangChain

llm = ChatAnthropic(model="claude-opus-4-7-20250514",callbacks=[HeadroomCallbackHandler()] # Add this one line
)

Everything else in your LangChain code is unchanged

response = llm.invoke("Analyse this large dataset: ...")
```

Mode 4: MCP Server (AI-Native Let the Model Decide)

The MCP mode installs Headroom as an MCP server, exposing three tools that the AI model itself can call when it decides compression is appropriate:

• headroom_compress— compress large content before reasoning over it
• headroom_retrieve— retrieve the original content if needed
• headroom_stats— see compression statistics for the current session

```

Install the MCP server (registers with Claude Code automatically)

headroom mcp install

For remote deployment (Docker/cloud)

headroom mcp install --remote http://proxy-host:8787/mcp
```

Once installed, Claude Code gains awareness of Headroom as a tool:

```

What happens during a Claude Code session with MCP mode:

You: Analyse the last 24 hours of production logs and identify
the root cause of the 3 AM incident
Claude Code: Let me read the production logs first.
[Reading: /var/log/app/production.log — 65,000 lines]
This log is very large. Let me compress it before analysing.
-> headroom_compress(
content="[65,694 tokens of log content]",
hint="error analysis"
)
<- {
"compressed": "[5,118 tokens — errors and warnings only]",
"hash": "a1b2c3d4",
"original_tokens": 65694,
"compressed_tokens": 5118,
"savings_percent": 92.2,
"transforms": ["router:log:0.92"]
}
The original is stored locally. Now analysing the compressed log...
[Finds FATAL OutOfMemoryError at 03:17:34]
[Traces it to TaskService.processBatch()]
[Identifies a missing pagination limit on a database query]
Root cause identified: The nightly batch job at 03:15 was
processing the full users table (2.3M records) without pagination.
At 2M records, the heap exhausted.
Recommendation: Add LIMIT 1000 and offset-based pagination to
TaskService.processBatch() at line 234.
Tokens saved this session: 60,576 (92.2%)
Estimated cost without Headroom: $0.98
Actual cost: $0.077
```
The model made the decision to compress. It retrieved what it needed. It answered correctly. You paid 92% less.

Measuring Your Actual Savings

```

Run Headroom's built-in performance benchmark

Uses real compression on sample data to estimate your savings

headroom perf

Expected output:

Running Headroom performance benchmark...

┌─────────────────────────────────────────────────────┐

│ Headroom Benchmark Results │

├──────────────────┬────────────┬────────────┬────────┤

│ Workload │ Original │ Compressed │ Saved │

├──────────────────┼────────────┼────────────┼────────┤

│ Log analysis │ 10,144 tok │ 1,260 tok │ 87.6% │

│ Code search │ 17,765 tok │ 1,408 tok │ 92.1% │

│ SRE debugging │ 65,694 tok │ 5,118 tok │ 92.2% │

│ JSON payload │ 8,420 tok │ 940 tok │ 88.8% │

├──────────────────┼────────────┼────────────┼────────┤

│ AVERAGE │ 25,506 tok │ 2,182 tok │ 90.2% │

└──────────────────┴────────────┴────────────┴────────┘

Estimated monthly savings at current usage:

Input tokens: 1.2M → 118K (-90%)

Estimated cost: $18.40 → $1.81 (saving $16.59/month)

See real-time statistics for the current session

headroom stats

See cumulative statistics across all sessions

headroom stats --all-time

Run a holdout experiment to measure savings on your actual traffic

export HEADROOM_OUTPUT_HOLDOUT=0.1 # Keep 10% uncompressed as control
headroom proxy --port 8787

Dashboard shows measured vs estimated savings with confidence bands

```

Getting Started in Under 5 Minutes

Here is the fastest path from zero to running Headroom:

If You Use Claude Code

```

Step 1: Install

pip install "headroom-ai[all]"

Step 2: Wrap Claude Code

headroom wrap claude

Step 3: Use Claude Code as normal

Headroom is now active — all context compressed automatically

claude "analyse the production logs for the last incident"

Step 4: Check your savings

headroom stats
```
Done. You changed nothing about how you use Claude Code. Headroom runs invisibly underneath.

If You Use Codex

pip install "headroom-ai[all]" headroom wrap codex codex "explain the authentication flow in this codebase" headroom stats

If You Use Cursor

```
pip install "headroom-ai[all]"
headroom wrap cursor

Restart Cursor — Headroom now active

headroom stats
```

If You Have an Existing Python AI Application

```

Step 1: Install

pip install "headroom-ai[all]"

Step 2: Start the proxy

headroom proxy --port 8787 &

Step 3: Point your application at the proxy

export ANTHROPIC_BASE_URL=http://127.0.0.1:8787

or

export OPENAI_BASE_URL=http://127.0.0.1:8787

Step 4: Run your application as normal

python my_ai_agent.py

Step 5: Check savings

headroom stats
```
Zero application code changes. Headroom intercepts everything automatically.

If You Want Library Mode (Maximum Control)

```

Install

pip install "headroom-ai[all]"

from headroom import compress
import anthropic
client = anthropic.Anthropic()

Your messages — potentially with large tool outputs

messages = [{"role": "user","content": "Find all errors in this log",},{"role": "user","content": open("production.log").read() # Could be 50,000 tokens}
]

Compress before sending

result = compress(messages, model="claude-opus-4-7-20250514")
print(f"Compressed {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

Send compressed version

response = client.messages.create(model="claude-opus-4-7-20250514",max_tokens=1000,messages=result.messages
)
print(response.content[0].text)
```

When Headroom Helps Most and When It Doesn't

Understanding where Headroom's savings concentrate helps you set realistic expectations.

Where You Will See 60–95% Savings

• Log file analysis:the classic use case. Log files are 95% routine operational noise. Only the FATAL and ERROR lines matter. Headroom extracts the signal.
• JSON tool outputs:any API response, database query result, or tool output with repeated field names, null values, and metadata. JSON tool outputs contain enormous amounts of repeated field names, null fields, and metadata the LLM rarely needs.
• Large code searches:agent code searches return full files when the model needs a few functions. AST-aware compression extracts the relevant code.
• RAG pipelines:RAG chunks frequently contain the same boilerplate (documentation headers, licence notices) across dozens of retrieved documents. Headroom deduplicates.
• SRE and DevOps workflows:anything involving incident logs, monitoring data, system state dumps.

Where You Will See 15–20% Savings

**Conversational coding sessions: ** when your context is mostly code you are actively writing and editing, Headroom's savings are smaller (but still meaningful at scale).

Short, focused queries: a 200-token prompt with a 100-token tool output does not compress as dramatically as a 65,000-token log.

Where Headroom Has Minimal Effect

Your own prose prompts: the savings come from compressing non-prose payloads, not human-written prompts. Your carefully crafted system prompt does not compress much. That is fine, it is not where the tokens are.;

Very small contexts: if your context is already efficient, there is less to compress.

The Privacy Advantage Nobody Talks About

Most context compression solutions send your data to a third-party server for processing. Headroom is different.

Local-first architecture: all compression runs on your infrastructure. Your source code, logs, and internal data never leave your environment.

For enterprise teams working with sensitive code, customer data, financial systems, health records, proprietary algorithms, this is not a nice-to-have. It is a hard requirement.

The compression algorithms run on your machine. The original content is cached locally. The LLM receives compressed content. Nothing touches an external compression service. You retain full auditability of everything that happened.

The reversible, local-first architecture addresses the two biggest barriers to enterprise AI adoption: data privacy and auditability. Organisations can now deploy AI agents at scale without compromising security or losing the ability to verify outputs.

Advanced Usage: Cross-Agent Memory

One of Headroom's less-covered features is cross-agent memory, allowing multiple AI tools to share context and avoid redundant work:

```

Claude Code and Codex can share compressed memory

Neither re-reads files the other has already processed

Also learns from failed sessions

headroom learn

Analyses your past sessions, identifies repeated errors,

and generates suggestions for CLAUDE.md or AGENTS.md

to prevent the same issues in future sessions

```
This means if Claude Code spent tokens understanding your authentication system this morning, Codex can access that compressed understanding this afternoon without reading the same files again.

The Bigger Picture: Why This Matters for AI at Scale

The 60–95% token reduction is not just about saving money. It is about enabling more complex agent workflows that were previously economically infeasible.

There are entire categories of AI agent tasks that are currently too expensive to run routinely:

• Full codebase analysis before every PR review
• Complete log ingestion for every incident
• Comprehensive RAG across entire documentation sets
• Multi-file context across large monorepos

These tasks are feasible in theory; the models can handle them. They are prohibitive in practice because the token cost at scale is enormous.

Headroom changes this calculus. When a task that cost $0.98 in tokens costs $0.077, the economics of running it routinely change completely. The agent workflows you avoided because they were too expensive become viable.

Just as CDNs revolutionised web performance by caching content closer to users, Headroom revolutionises AI economics by compressing content before it hits the billing boundary.

The cheapest token is the one you never send.

Quick Reference: Every Command You Need

```

── INSTALLATION ──────────────────────────────────────────────

pip install "headroom-ai[all]" # Python — everything
pip install headroom-ai # Python — core library only
pip install "headroom-ai[proxy]" # Proxy + MCP server
pip install "headroom-ai[ml]" # ML compression (needs torch)
pip install "headroom-ai[langchain]" # LangChain integration
npm install headroom-ai # TypeScript / Node.js

macOS Apple Silicon (recommended)

uv tool install --python 3.13 "headroom-ai[all]"

Docker

docker pull ghcr.io/headroomlabs-ai/headroom:latest
docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest

── WRAP MODE ─────────────────────────────────────────────────

headroom wrap claude # Wrap Claude Code
headroom wrap codex # Wrap OpenAI Codex CLI
headroom wrap cursor # Wrap Cursor
headroom wrap aider # Wrap Aider
headroom wrap copilot --subscription # Wrap GitHub Copilot CLI
headroom wrap opencode # Wrap OpenCode
headroom unwrap claude # Remove Headroom from Claude Code

── PROXY MODE ────────────────────────────────────────────────

headroom proxy --port 8787 # Start proxy on port 8787
headroom proxy --port 8787 --verbose # With real-time logging
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787 # Point Claude at it
export OPENAI_BASE_URL=http://127.0.0.1:8787 # Point OpenAI at it

── MCP MODE ──────────────────────────────────────────────────

headroom mcp install # Install as MCP server (local)
headroom mcp install --remote http://proxy-host:8787/mcp # Remote
headroom mcp status # Check MCP server status

── MEASUREMENT ───────────────────────────────────────────────

headroom perf # Run benchmark
headroom stats # Current session stats
headroom stats --all-time # Cumulative stats
export HEADROOM_OUTPUT_HOLDOUT=0.1 # 10% holdout for A/B measurement

── LEARNING ──────────────────────────────────────────────────

headroom learn # Learn from past sessions# Generates CLAUDE.md suggestions

── GITHUB ────────────────────────────────────────────────────

https://github.com/headroomlabs-ai/headroom

Apache 2.0 — free for commercial use

```

References

[1] Pasquale Pillitteri. Headroom Cuts AI Tokens 60-95%: a Netflix Engineer's Tool. June 20, 2026. https://pasqualepillitteri.it/en/news/5659/headroom-context-compression-ai-agents

[2] Let's Data Science. Netflix engineer open-sources Headroom to cut AI token costs. May 31, 2026. https://letsdatascience.com/news/netflix-engineer-open-sources-headroom-to-cut-ai-token-costs

[3] AI Engineering / Medium. Headroom: Netflix Engineer's Open-Source Context Compression Tool. June 2026. https://ai-engineering-trend.medium.com/headroom-netflix-engineers-open-source-context-compression-tool

[4] GitHub / headroomlabs-ai. Headroom — Official Repository. https://github.com/headroomlabs-ai/headroom

[5] Undercode Testing. Headroom: The Netflix-Backed Open-Source Proxy That Slashes AI Token Costs By 95%. June 19, 2026. https://undercodetesting.com/headroom-the-netflix-backed-open-source-proxy

[6] OMC News. Hot Repo: Netflix's $700K Token-Saver Just Went Open Source. June 2, 2026. https://news.one-man-company.com/news/hot-repo-headroom-token-compression

[7] DevShelfHub. Headroom AI: Context Compression Library — 2026 Deep Dive. June 19, 2026. https://www.devshelfhub.com/articles/headroom-ai-context-compression-layer-for-ai-agents/

[8] Headroom Official Documentation. https://headroomlabs-ai.github.io/headroom/

[9] MCP Tools — Headroom. https://headroom-docs.vercel.app/docs/mcp

[10] DEV Community. Headroom: Cut Your LLM Token Usage by Up to 95%. June 4, 2026. https://dev.to/arshtechpro/headroom-cut-your-llm-token-usage-by-up-to-95