Skip to content
BSWEN
Blog

How to Use Headroom to Compress LLM Context in 5 Minutes

Cowrie
Cowrie
Dev @ Bswen

Purpose

This post shows how to install Headroom and compress LLM context in under 5 minutes. I will cover both the Python SDK and the proxy mode, because the fastest path depends on your setup.

Environment

  • Python 3.10+ (tested on 3.11)
  • pip or pipenv
  • An OpenAI API key (or Anthropic, Google, Azure)

Installation

I installed Headroom with the all extra to get everything including proxy support:

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

If you only need the Python SDK, pip install headroom-ai is enough. But the proxy command needs the extra.

Option 1: Proxy Mode (Zero Code Changes)

The proxy is the fastest way to start. It sits between your app and the LLM provider at the HTTP level.

Start proxy
headroom proxy --port 8787

Then point any OpenAI-compatible client at it:

Point Claude Code at proxy
ANTHROPIC_BASE_URL=http://localhost:8787 claude

Or set OPENAI_BASE_URL=http://localhost:8787/v1 for Cursor or Codex. Everything else works exactly the same, but requests get compressed automatically.

Check stats in another terminal:

Check stats
curl http://localhost:8787/stats

I saw {"requests_total": 12, "tokens_saved_total": 45000, ...} after my first few calls.

Option 2: Python SDK (Explicit Control)

If you want direct control, use the compress() function:

sdk_example.py
from headroom import compress
import json


messages = [
    {"role": "system", "content": "You analyze search results."},
    {"role": "user", "content": "Search for Python tutorials."},
    {"role": "tool", "tool_call_id": "call_1",
     "content": json.dumps({"results": [{"title": f"Result {i}", "score": 100-i} for i in range(500)]})},
]


result = compress(messages, model="gpt-4o")
print(f"Tokens before: {result.tokens_before}")   # 45000
print(f"Tokens after:  {result.tokens_after}")    # 4500
print(f"Compression:   {result.compression_ratio:.0%}")  # 90%

This gives you the same compression as the proxy, but you decide exactly when and what to compress.

What I Got Wrong at First

I initially installed only headroom-ai without [all]. When I tried headroom proxy, the command was missing. The error was:

Missing proxy error
headroom: error: invalid choice: 'proxy'

The fix was pip install "headroom-ai[all]". The proxy dependencies are optional.

How It Works

Both paths use the same compression engine:

  1. Detect content type (JSON, code, logs, text)
  2. Route to the optimal compressor
  3. Apply provider-specific cache optimizations
  4. Forward to the LLM

You do not need to configure anything for basic use. The defaults handle most workloads.

Summary

In this post, I showed how to install Headroom and get compression working in 5 minutes. The key point is that proxy mode is fastest for zero-code adoption, while the SDK gives explicit control. Pick proxy if you use Claude Code or Cursor; pick SDK if you build LangChain or custom apps.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: