# How to Report a Bug in Headroom: A Complete Guide to Issues and PRs

> Learn how to report a bug in Headroom effectively. Enable debug logging, create a test case, and submit a detailed GitHub issue for quick resolution.

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

---

**To report a bug in Headroom, enable debug logging with `--log-level debug`, create a minimal reproducible test case, and open a GitHub issue at `chopratejas/headroom` with full environment details and stack traces.**

Headroom is a local-first compression layer that sits between AI agents and LLM providers, utilizing a modular pipeline of transforms to compress and cache data. Because its architecture involves sequential components like `CacheAligner` and `CodeCompressor`, bugs can surface at multiple integration points. Knowing how to report a bug in Headroom effectively ensures maintainers can quickly triage issues across the proxy, transforms, or caching layers.

## Understanding Headroom's Architecture

### The Transform Pipeline

Headroom processes requests through a **pipeline of transforms** including `CacheAligner`, `ContentRouter`, `SmartCrusher`, `CodeCompressor`, and `Kompress-base`. These components sequentially compress, cache, and potentially retrieve original data according to the architecture documented in [`README.md`](https://github.com/chopratejas/headroom/blob/main/README.md).

### Common Bug Categories

Bugs typically emerge in these distinct layers:

- **Proxy / CLI**: Incorrect flag handling, environment-variable parsing, or bad exit codes
- **Transforms**: JSON-crushing errors, AST parsing crashes, or model loading failures
- **Cache / CCR**: Missed cache keys or unrecoverable retrieval requests
- **Debug logging**: Missing debug output or silent failures

## Step-by-Step Bug Reporting Process

### 1. Gather Context with Debug Logging

Run the problematic command with debug logging enabled to capture internal transformer decisions:

```bash
headroom proxy --log-level debug

```

Record the exact command line, environment variables (`HEADROOM_*`), Python/Node versions, and OS details.

### 2. Create a Minimal Reproduction

Reduce the input to the smallest JSON, code snippet, or text that still triggers the failure. For proxy issues, a short `curl` request against the running proxy is often sufficient. According to [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md), every bug report must include a **reproducible test case**.

### 3. Open a GitHub Issue

Navigate to the Headroom issue tracker at `https://github.com/chopratejas/headroom/issues` and select "New issue". Include:

- **Title**: Concise description (e.g., "Crash in `CodeCompressor` when handling empty function bodies")
- **Description**: Minimal repro, full command line, environment dump, and debug log excerpt
- **Expected vs. Actual behavior**: Clear description of what should happen versus observed behavior

### 4. Submit a Pull Request (Optional)

If you already have a fix, open a pull request instead of an issue. The PR must contain the reproducing test and pass the repository's CI (`uv run pytest`). The contribution guide requires a **"Real behavior proof"** section in the PR body describing how you verified the fix.

## Required Information for Bug Reports

The project requires specific artifacts to process bug reports efficiently:

- Full command line and environment variables (`HEADROOM_*`)
- Debug log output from `--log-level debug`
- Minimal input payload triggering the crash
- Stack trace from the failure point
- Automated test that fails before the fix and passes after

## Code Examples for Reproducing Issues

### Enabling Debug Logging

Capture comprehensive debug output when reproducing proxy failures:

```bash

# Start the proxy with full debug output

headroom proxy --log-level debug --port 8787 &
PROXY_PID=$!

# Example request that triggers the bug

curl -X POST http://127.0.0.1:8787/v1/messages \
    -H "Content-Type: application/json" \
    -d '{"model":"gpt-4o","messages":[{"role":"user","content":"trigger bug"}]}' \
    > response.json 2> debug.log

# Stop the proxy after capture

kill $PROXY_PID

```

Inspect `debug.log` for stack traces and transformer selection (look for lines like `CacheAligner → ContentRouter → CCR`).

### Writing a Minimal Test Case

Attach a pytest test case that reproduces the issue:

```python
import pytest
from headroom import compress

def test_bug_trigger():
    """Minimal reproduction of the compression bug."""
    payload = [{"role": "user", "content": "trigger bug"}]
    with pytest.raises(RuntimeError, match="unexpected token"):
        compress(messages=payload, model="gpt-4o")

```

Place this under `tests/` and verify it fails before your fix and passes after.

### Creating Issues via CLI

Use the GitHub CLI to create structured bug reports:

```bash
gh issue create \
  --repo chopratejas/headroom \
  --title "Crash in CodeCompressor with empty function bodies" \
  --body "$(cat <<EOF
**Steps to reproduce**

1. Start proxy with debug logging:
   \`\`\`bash
   headroom proxy --log-level debug
   \`\`\`

2. Send the following request:
   \`\`\`json
   { "model": "gpt-4o", "messages": [{ "role": "user", "content": "def foo(): pass" }] }
   \`\`\`

**Observed behavior**
Process aborts with stack trace (see attached debug.log).

**Expected behavior**
Should compress without error.

**Environment**
- OS: macOS 14.6
- Python: 3.12.3
- Headroom version: 0.9.1
EOF
)" \
  --label "bug"

```

## Key Files to Reference

When investigating or reporting bugs, consult these source locations:

- **[`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md)**: Defines required reproduction steps, test inclusion criteria, and "Real behavior proof" requirements for PRs
- **[`README.md`](https://github.com/chopratejas/headroom/blob/main/README.md)**: Documents the high-level architecture helping pinpoint which pipeline layer contains the bug
- **[`wiki/troubleshooting.md`](https://github.com/chopratejas/headroom/blob/main/wiki/troubleshooting.md)**: Explains debug logging (`--log-level debug`) and log interpretation
- **`headroom/transforms/*`**: Source code for individual compressors; critical when isolating transform-specific bugs
- **[`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py)**: Core request-handling entry point containing routing logic for proxy-related crashes

## Summary

- Headroom's modular transform pipeline means bugs can originate in the **Proxy**, **Transforms**, **Cache**, or **logging** layers
- Always enable **`--log-level debug`** before capturing bug behavior to expose transformer decisions
- Include a **minimal reproducible test case** and environment details in every report
- Submit issues at `chopratejas/headroom/issues` with clear titles and observed versus expected behavior
- Pull requests must include failing tests and pass `uv run pytest` according to [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md)

## Frequently Asked Questions

### What information is required when I report a bug in Headroom?

You must provide a reproducible test case, the exact command line used, environment variables (particularly `HEADROOM_*` vars), debug logs from `--log-level debug`, and a clear description of expected versus actual behavior. The [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md) file explicitly requires an automated test that fails before the fix and passes after.

### How do I capture debug logs for a Headroom proxy crash?

Start the proxy with `headroom proxy --log-level debug` and reproduce the failure. The debug output includes transformer selection decisions (e.g., `CacheAligner → ContentRouter`) and full stack traces. Save this output to a file and attach it to your GitHub issue.

### Where should I look if the bug is in the compression logic?

Inspect the `headroom/transforms/` directory, which contains `CodeCompressor`, `SmartCrusher`, and other transform implementations. If the crash involves AST parsing or JSON crushing, the specific transform file will contain the relevant error handling and logic to investigate.

### Can I submit a fix directly without opening an issue first?

Yes. If you already have a fix, open a pull request directly. Ensure your PR includes a test that reproduces the bug and passes the CI suite (`uv run pytest`). Include a "Real behavior proof" section in the PR body describing how you verified the fix, as required by the contribution guidelines.