# How to Contribute to the Headroom Project: Complete Setup and Workflow Guide

> Contribute to the Headroom project by forking the repo, setting up your environment with uv sync, and installing git hooks. Submit PRs with real behavior proof and maintain P99 latency goals.

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

---

**To contribute to the headroom project, fork the `chopratejas/headroom` repository, configure your environment using `uv sync --extra dev`, install pre-commit hooks with `make install-git-hooks`, and submit a pull request that includes "Real behavior proof" and maintains the P99 latency target of approximately 50ms for transforms.**

The headroom project is a Python-centric AI-assistant tool that prioritizes safety, performance, and extensibility. Whether you are fixing bugs, adding features, or improving documentation, following the structured workflow defined in [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md) ensures your contributions meet the repository's rigorous standards for code quality and security.

## Setting Up Your Development Environment

A reproducible development environment is essential for contributing to the headroom project. The repository supports both local Python setups with `uv` and VS Code dev containers for immediate productivity.

### Fork and Clone the Repository

Begin by creating a personal fork on GitHub, then clone it locally and create a feature branch:

```bash
git clone https://github.com/<your-username>/headroom.git
cd headroom
git checkout -b my-feature-branch main

```

### Install Dependencies and Git Hooks

The project uses `uv` for fast dependency management. Run the following commands to install development dependencies and enable automated checks:

```bash
python -m venv .venv && source .venv/bin/activate
uv sync --extra dev
make install-git-hooks

```

The `make install-git-hooks` command configures pre-commit hooks, commitlint, and other automated checks defined in the repository configuration. Alternatively, you can use the provided VS Code dev containers ([`.devcontainer/devcontainer.json`](https://github.com/chopratejas/headroom/blob/main/.devcontainer/devcontainer.json) or [`.devcontainer/memory-stack/devcontainer.json`](https://github.com/chopratejas/headroom/blob/main/.devcontainer/memory-stack/devcontainer.json)) for a containerized environment with all dependencies pre-installed.

## Understanding the Contribution Workflow

Before writing code, determine where your contribution fits within the project structure. The [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md) file contains a "Where does my contribution go?" table that categorizes changes by type.

**Key contribution types include:**

- **Bug fixes** – Corrections to existing functionality with regression tests
- **Features** – New transforms, providers, or capabilities that extend the AI-assistant pipeline
- **Documentation** – Improvements to README, docstrings, or architectural guides

Every contribution must satisfy the "Real behavior proof" requirement documented in lines 34-44 of [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md). This section requires you to document your OS, Python version, exact commands run, and terminal output or screenshots demonstrating the fix works in a real environment.

## Implementing Code Changes

The headroom project enforces strict coding standards to maintain transform performance and reliability.

### Code Quality Standards

All code must pass linting and formatting checks using **Ruff**:

```bash
uv run ruff check .
uv run ruff format .

```

### Testing Requirements

Add or update unit and integration tests using `pytest`:

```bash
uv run pytest

```

Tests should cover both success paths and edge cases, particularly for new transforms in the `headroom/transforms/` directory.

### Performance Constraints

As implemented in `chopratejas/headroom`, transforms must maintain a P99 latency target of approximately 50ms. When modifying `headroom/transforms/*` files, benchmark your changes to ensure they do not introduce performance regressions in the processing pipeline.

## Submitting Your Pull Request

The PR workflow requires careful attention to formatting and validation.

### Commit Message Format

Follow the conventional commit format (`feat:`, `fix:`, `docs:`, etc.) to satisfy the commit-msg hooks installed earlier. The repository enforces these standards automatically, so non-compliant commits will be rejected.

### Pre-Submission Checklist

Before pushing your branch, verify CI passes locally:

```bash
uv run pytest
uv run ruff check .

```

### Opening the Pull Request

Push your branch and open a PR on GitHub with a clear, descriptive title. Include the following in your PR description:

1. A "Real behavior proof" section detailing your environment and demonstrating the change
2. References to any related issues
3. Completion of the review-readiness checkboxes from the PR template

The repository caps contributions at **ten open PRs per author**, so complete existing work before opening new requests.

## Example: Adding a New Transform

Below is a complete example of contributing a new transform to the headroom pipeline. This implementation adds an `UpperCaseTransform` that converts text messages to uppercase.

Create the transform implementation in [`headroom/transforms/uppercase.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/uppercase.py):

```python
from headroom.transforms.base import TransformBase

class UpperCaseTransform(TransformBase):
    """Converts all text messages to uppercase."""
    
    def apply(self, content: str) -> str:
        return content.upper()

```

Register the transform in [`headroom/transforms/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/__init__.py):

```python
from .uppercase import UpperCaseTransform

__all__ = ["UpperCaseTransform", ...]  # add to existing exports

```

Add corresponding tests in [`tests/test_transforms.py`](https://github.com/chopratejas/headroom/blob/main/tests/test_transforms.py):

```python
def test_uppercase_transform():
    t = UpperCaseTransform()
    assert t.apply("hello") == "HELLO"

```

Run the full test suite to verify your changes before submission:

```bash
uv run pytest

```

## Summary

- **Fork and clone** the `chopratejas/headroom` repository, then run `uv sync --extra dev` and `make install-git-hooks` to configure your environment.
- **Follow coding standards** using Ruff for linting and formatting, and maintain the P99 latency target of ~50ms for all transforms.
- **Provide "Real behavior proof"** in every PR, documenting your environment, commands run, and evidence that the fix works.
- **Limit open PRs** to ten per author and use conventional commit formats (`feat:`, `fix:`, etc.) to pass automated checks.
- **Reference key files** including [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md), [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml), and `headroom/transforms/` when implementing changes.

## Frequently Asked Questions

### What is the maximum number of PRs I can have open simultaneously?

The headroom project limits contributors to **ten open pull requests at a time**. This policy ensures quality over quantity and prevents review backlog. Complete and merge existing PRs before opening new ones according to the [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md) guidelines.

### What is "Real behavior proof" and why is it required?

"Real behavior proof" is a mandatory PR section where you document your operating system, Python version, provider/model settings, exact commands executed, and terminal output or screenshots proving the change works. This requirement, specified in lines 34-44 of [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md), ensures that contributions are validated in realistic environments rather than just theoretical test cases.

### How do I set up the development environment without installing Python locally?

Use the provided VS Code dev containers located in [`.devcontainer/devcontainer.json`](https://github.com/chopratejas/headroom/blob/main/.devcontainer/devcontainer.json) or [`.devcontainer/memory-stack/devcontainer.json`](https://github.com/chopratejas/headroom/blob/main/.devcontainer/memory-stack/devcontainer.json). These containers provide a pre-configured environment with all dependencies installed, allowing you to contribute to the headroom project without local Python setup.

### What are the performance requirements for new transforms?

All transforms in `headroom/transforms/` must maintain a P99 latency of approximately 50 milliseconds. When you contribute to the headroom project, benchmark your transforms to ensure they meet this performance threshold, as the architecture prioritizes low-latency AI-assistant interactions.