How to Get Started with Developing Headroom: A Complete Guide for Contributors

To start developing Headroom, clone the repository, install dependencies with uv sync --extra dev or pip install -e ".[dev]", and run the proxy locally with headroom proxy --port 8787 to test changes without modifying upstream code.

Headroom is a context-compression layer that sits between LLM-enabled agents and model providers like OpenAI and Anthropic. Whether you want to add new compression transforms, optimize the caching layer, or integrate additional providers, understanding the codebase structure in chopratejas/headroom is essential. This guide walks you through setting up your development environment, exploring the architecture, and making your first contribution.

Understanding Headroom's Architecture

Headroom operates in three interchangeable modes: Library (in-process SDK), Proxy (HTTP wrapper), and Wrap (CLI agent launcher). The core implementation spans several key modules:

• SDK Entry Point: headroom/__init__.py lazily exposes the public API, including HeadroomClient and the compress function【L14-L22】
• Client Implementation: headroom/client.py orchestrates request handling, token counting, pipeline execution, and metric storage【L56-L120】
• Transform Pipeline: Individual transforms like SmartCrusher and CacheAligner live in headroom/transforms/, orchestrated by TransformPipeline.apply in headroom/transforms/pipeline.py【L1-L30】
• Cache Optimizers: Provider-specific optimizers in headroom/cache/ integrate with the client when enable_cache_optimizer=True【L41-L56】
• Proxy Server: The ASGI implementation in headroom/proxy/server.py forwards requests and injects runtime environment variables【L1-L30】
• Storage Layer: Request metrics persist via SQLite or JSON-L through headroom/storage/sqlite.py【L1-L30】

Setting Up Your Development Environment

Headroom targets Python 3.10+. While pip works, the project prefers uv for dependency management.

Clone the repository and install development dependencies:

git clone https://github.com/chopratejas/headroom.git
cd headroom

# Using uv (recommended)

uv sync --extra dev

# Or using pip

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

This installs the SDK, proxy, and development tools including pytest, mypy, and pre-commit. Verify your installation by running the test suite:

uv run pytest

Running Headroom in Development Mode

The fastest way to test changes is running the local proxy, which requires zero code modifications to existing applications.

Start the proxy server:

headroom proxy --port 8787

Verify the health endpoint:

curl http://localhost:8787/health

The console displays pipeline stage completions (e.g., Pipeline complete: 45,000 → 4,500 tokens), confirming that headroom/proxy/server.py is correctly routing requests through the transform pipeline.

To test the Python SDK directly, create a client instance that wraps an OpenAI client:

from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain Headroom in one sentence"}],
)
print(response.choices[0].message.content)
print("Tokens saved:", client.get_stats()["session"]["tokens_saved_total"])

The request flow follows: client._create → TransformPipeline.apply → CacheOptimizer → call_client_transport【L94-L140】.

Customizing the Compression Pipeline

You can modify pipeline behavior without touching core source code by passing a HeadroomConfig object. The configuration class is defined in headroom/config.py and referenced throughout the client initialization【L18-L24】.

Adjust transform parameters like SmartCrusher's retention limits:

from headroom import HeadroomClient, OpenAIProvider, HeadroomConfig

cfg = HeadroomConfig()
cfg.smart_crusher.max_items_after_crush = 30  # default is 15

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    config=cfg,
)

For proxy-based testing, point any OpenAI-compatible client at your local instance:

export OPENAI_BASE_URL=http://localhost:8787/v1
python your_existing_script.py

Contributing New Features

Adding a Custom Transform

Create a new file under headroom/transforms/ implementing the BaseTransform protocol:

# headroom/transforms/my_transform.py

from .base import BaseTransform, TransformResult

class MyTransform(BaseTransform):
    name = "my_transform"

    def apply(self, messages, tokenizer, **kwargs) -> TransformResult:
        new_msgs = []
        for msg in messages:
            if msg["role"] == "assistant" and tokenizer.count_message(msg) > 500:
                continue
            new_msgs.append(msg)
        return TransformResult(messages=new_msgs, transforms_applied=[self.name])

Register your transform in headroom/transforms/__init__.py by adding it to the __all__ list so the pipeline discovers it automatically.

Running Benchmarks

Before submitting changes, validate performance using the benchmark suite:

uv run python -m headroom.evals suite --tier 1

The harness reuses the same client code as production, providing realistic feedback on token savings and latency impact.

Submission Checklist

Run pre-commit hooks before opening a pull request:

pre-commit run --all-files

Consult CONTRIBUTING.md for the complete submission checklist and coding standards.

Summary

• Repository structure: Core logic resides in headroom/client.py, transforms in headroom/transforms/, and the proxy server in headroom/proxy/server.py
• Setup: Use uv sync --extra dev or pip install -e ".[dev]" to install Python 3.10+ dependencies
• Testing: Run headroom proxy --port 8787 for integration testing or uv run pytest for unit tests
• Customization: Modify HeadroomConfig to adjust compression parameters without altering core transforms
• Extension: Implement BaseTransform in headroom/transforms/ and register in __init__.py to add new compression strategies

Frequently Asked Questions

What Python version does Headroom require?

Headroom requires Python 3.10 or higher. The project uses modern type hints and async features that necessitate this version. The pyproject.toml specifies compatible versions, and the CI pipeline tests against 3.10, 3.11, and 3.12.

How do I test my changes without modifying existing agent code?

Use the Proxy mode. Run headroom proxy --port 8787 and set OPENAI_BASE_URL=http://localhost:8787/v1 in your environment. Existing OpenAI-compatible clients automatically route through Headroom without code changes, allowing you to test transforms against real workloads.

Where should I add a new compression algorithm?

Create your implementation in headroom/transforms/your_algorithm.py following the BaseTransform protocol. Reference existing implementations like smart_crusher.py for the interface structure. Then register the class in headroom/transforms/__init__.py to include it in the automatic pipeline discovery.

How does Headroom handle token counting across different providers?

The HeadroomClient in headroom/client.py delegates to provider-specific implementations configured via the provider parameter. Each provider class (e.g., OpenAIProvider, AnthropicProvider) implements tokenization logic appropriate to that API, ensuring accurate compression metrics regardless of the underlying model.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}