How to Configure Headroom for Claude Code, Codex, Cursor, and Aider

Headroom functions as a local compression proxy that sits between your coding agent and the LLM provider, and you configure it for Claude Code, Codex, Cursor, or Aider by running headroom wrap <agent> with agent-specific flags and environment variables defined in headroom/cli/wrap.py and individual provider modules.

The chopratejas/headroom repository implements a token-reduction layer that intercepts HTTP traffic between AI coding agents and their upstream LLM providers. When you invoke headroom wrap <agent>, the command starts an ASGI proxy server and launches the target agent with injected HEADROOM_* environment variables that force all LLM traffic through the local compression pipeline. Each agent requires distinct configuration options because they authenticate and communicate with providers differently.

How the Headroom Proxy Architecture Works

Headroom inserts a local ASGI server between your coding agent and the LLM provider. The proxy implements a compression pipeline consisting of CacheAligner → ContentRouter → SmartCrusher / CodeCompressor / Kompress-base, followed by CCR (Context-Cache-Recall) to store original content locally.

When you run headroom wrap <agent>, the wrapper defined in headroom/cli/wrap.py performs two operations:

1. Starts the Headroom proxy on a local port (default 8787).
2. Launches the agent with environment variables pointing its API client at the proxy instead of the upstream provider.

The wrapper also applies agent-specific logic, such as normalizing tool-search settings for Claude Code or detecting ChatGPT authentication modes for Codex.

Global Configuration Environment Variables

Before wrapping any agent, you can export these variables to control the proxy behavior globally:

• HEADROOM_CONTEXT_TOOL – Selects the CLI context helper (rtk or lean-ctx). Default is rtk. Set via _CONTEXT_TOOL_ENV in wrap.py.
• HEADROOM_KOMPRESS_BACKEND – Controls the Kompress model backend (auto, onnx, pytorch, pytorch_mps). Default is auto.
• HEADROOM_BETA_HEADER_STICKY – Re-injects anthropic-beta or OpenAI-Beta headers for cache stability. Default is enabled.
• HEADROOM_OUTPUT_SHAPER – Reduces output tokens from the model. Set to 1 to enable; default is 0 (off).
• HEADROOM_WRAP_PROXY_TIMEOUT – Seconds to wait for the proxy to become ready before launching the agent. Default is 45 seconds (or 90 seconds when ML modules are required), read via _WRAP_PROXY_TIMEOUT_ENV.

Agent-Specific Configuration Options

Claude Code Configuration

Claude Code support is handled in headroom/providers/claude/__init__.py with additional logic in headroom/cli/wrap.py.

• Tool-search deferral – The wrapper sets ENABLE_TOOL_SEARCH to true by default via the _configure_tool_search_env function (lines 58–83 in wrap.py), preventing Claude from loading unnecessary built-in tools.
• Persistent memory – Add the --memory flag to enable the cross-agent CCR store.
• Code-graph indexing – Use --code-graph to index the project for architectural queries; this adds approximately 200 tokens of overhead.

# Basic wrap

headroom wrap claude

# With memory and code-graph

headroom wrap claude --memory --code-graph

Codex Configuration

Codex configuration lives in headroom/providers/codex/__init__.py.

• Authentication detection – The wrapper automatically detects whether you are using standard OpenAI or Azure ChatGPT authentication via codex_uses_chatgpt_auth.
• Project tagging – The --project flag injects an X-Headroom-Project header derived from the launch directory for usage aggregation.

# Simple launch

headroom wrap codex

# With explicit project tag

headroom wrap codex --project my-library

Cursor Configuration

Cursor does not support native proxy injection, so the wrapper only prints the configuration URL for manual entry.

• Manual URL entry – Run headroom wrap cursor and copy the printed HEADROOM_BASE_URL (e.g., http://localhost:8787) into Cursor’s Settings under “Proxy URL”.

headroom wrap cursor

# Output: HEADROOM_BASE_URL=http://localhost:8787

# Paste this into Cursor → Settings → Proxy URL

Aider Configuration

Aider integration is managed by headroom/providers/aider/__init__.py via the build_launch_env function.

• Launch environment – The wrapper injects HEADROOM_AIDER_* variables and the proxy URL automatically.
• Shared memory – The --memory flag works identically to Claude Code, utilizing the same CCR store.

headroom wrap aider --memory

Practical Configuration Examples

Custom Port and Context Tool

To run Claude Code with the lean-ctx context tool on a non-standard port:

export HEADROOM_CONTEXT_TOOL=lean-ctx
headroom wrap claude --no-context-tool --port 9999

Apple Silicon Kompress Backend

Enable the MPS backend for Kompress on Apple Silicon:

export HEADROOM_KOMPRESS_BACKEND=pytorch_mps
headroom wrap claude

Python SDK Per-Request Overrides

For programmatic control, use the Headroom Python SDK to override compression settings for individual requests:

from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
    enable_cache_optimizer=True,
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain the algorithm"}],
    headroom_mode="audit",
    headroom_output_buffer_tokens=8000,
)

Summary

• Headroom wraps agents by starting a local proxy and injecting HEADROOM_* environment variables via headroom/cli/wrap.py.
• Global options like HEADROOM_KOMPRESS_BACKEND and HEADROOM_OUTPUT_SHAPER apply to every wrapped agent.
• Claude Code uses --memory, --code-graph, and tool-search deferral via _configure_tool_search_env.
• Codex supports --project tags and automatic auth detection in headroom/providers/codex/__init__.py.
• Cursor requires manual paste of the proxy URL because it lacks native environment variable support.
• Aider is configured through build_launch_env in headroom/providers/aider/__init__.py and supports the same --memory flag as Claude Code.

Frequently Asked Questions

How do I change the Kompress backend for different hardware?

Set the HEADROOM_KOMPRESS_BACKEND environment variable to onnx, pytorch, or pytorch_mps (for Apple Silicon) before running headroom wrap. The default auto setting attempts to detect the optimal backend. See the configuration wiki in the repository for the full selection logic.

Why does Cursor require manual configuration while other agents work automatically?

Cursor’s application architecture does not read standard proxy environment variables like HTTP_PROXY or OPENAI_BASE_URL from the shell environment. Instead, it only accepts a base URL through its graphical settings interface. Therefore, headroom wrap cursor prints the HEADROOM_BASE_URL for you to copy into Cursor’s settings manually, unlike Claude Code or Aider which accept environment variables injected by the wrapper.

Can I share memory contexts between Claude Code and Aider?

Yes. Both agents support the --memory flag, which connects them to the same CCR (Context-Cache-Recall) store. When you enable this flag on either agent, Headroom persists conversation context locally, allowing you to switch between Claude Code and Aider without losing the compressed context history.

What is the difference between the rtk and lean-ctx context tools?

rtk (the default) is the full context helper that provides rich repository context for the LLM, while lean-ctx is a lighter alternative that reduces token overhead for smaller projects. You can switch between them by setting HEADROOM_CONTEXT_TOOL=lean-ctx before wrapping your agent, or disable context tooling entirely with --no-context-tool if you use a custom context manager.

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