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

> Configure Headroom for Claude Code, Codex, Cursor, and Aider using simple wrap commands. Optimize your local compression proxy for seamless LLM integration and enhanced coding.

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

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/claude/__init__.py) with additional logic in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.

```bash

# 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`](https://github.com/chopratejas/headroom/blob/main/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.

```bash

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

```bash
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`](https://github.com/chopratejas/headroom/blob/main/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.

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

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

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

```python
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.