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

> Learn how to get started with developing Headroom. Clone the repo, install dependencies, and run the proxy locally for seamless contributions. Your complete guide awaits!

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: getting-started
- Published: 2026-06-21

---

**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`](https://github.com/chopratejas/headroom/blob/main/headroom/__init__.py) lazily exposes the public API, including `HeadroomClient` and the `compress` function【[L14-L22](https://github.com/chopratejas/headroom/blob/main/headroom/__init__.py#L14)】
- **Client Implementation**: [`headroom/client.py`](https://github.com/chopratejas/headroom/blob/main/headroom/client.py) orchestrates request handling, token counting, pipeline execution, and metric storage【[L56-L120](https://github.com/chopratejas/headroom/blob/main/headroom/client.py#L56)】
- **Transform Pipeline**: Individual transforms like `SmartCrusher` and `CacheAligner` live in `headroom/transforms/`, orchestrated by `TransformPipeline.apply` in [`headroom/transforms/pipeline.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/pipeline.py)【[L1-L30](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/pipeline.py#L1)】
- **Cache Optimizers**: Provider-specific optimizers in `headroom/cache/` integrate with the client when `enable_cache_optimizer=True`【[L41-L56](https://github.com/chopratejas/headroom/blob/main/headroom/client.py#L41)】
- **Proxy Server**: The ASGI implementation in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py) forwards requests and injects runtime environment variables【[L1-L30](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py#L1)】
- **Storage Layer**: Request metrics persist via SQLite or JSON-L through [`headroom/storage/sqlite.py`](https://github.com/chopratejas/headroom/blob/main/headroom/storage/sqlite.py)【[L1-L30](https://github.com/chopratejas/headroom/blob/main/headroom/storage/sqlite.py#L1)】

## 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:

```bash
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:

```bash
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:

```bash
headroom proxy --port 8787

```

Verify the health endpoint:

```bash
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`](https://github.com/chopratejas/headroom/blob/main/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:

```python
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](https://github.com/chopratejas/headroom/blob/main/headroom/client.py#L94)】.

## 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`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) and referenced throughout the client initialization【[L18-L24](https://github.com/chopratejas/headroom/blob/main/headroom/client.py#L18)】.

Adjust transform parameters like `SmartCrusher`'s retention limits:

```python
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:

```bash
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:

```python

# 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`](https://github.com/chopratejas/headroom/blob/main/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:

```bash
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:

```bash
pre-commit run --all-files

```

Consult [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md) for the complete submission checklist and coding standards.

## Summary

- **Repository structure**: Core logic resides in [`headroom/client.py`](https://github.com/chopratejas/headroom/blob/main/headroom/client.py), transforms in `headroom/transforms/`, and the proxy server in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/__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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/your_algorithm.py) following the `BaseTransform` protocol. Reference existing implementations like [`smart_crusher.py`](https://github.com/chopratejas/headroom/blob/main/smart_crusher.py) for the interface structure. Then register the class in [`headroom/transforms/__init__.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.