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

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

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:

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 or .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 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. 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:

uv run ruff check .
uv run ruff format .

Testing Requirements

Add or update unit and integration tests using pytest:

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:

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:

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:

from .uppercase import UpperCaseTransform

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

Add corresponding tests in tests/test_transforms.py:

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

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

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, 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 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, 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 or .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.

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