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

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.

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:

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

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

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:

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: Defines required reproduction steps, test inclusion criteria, and "Real behavior proof" requirements for PRs
• README.md: Documents the high-level architecture helping pinpoint which pipeline layer contains the bug
• 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: 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

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

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