# How to Use headroom wrap to Integrate Claude Code, Cursor, and Aider

> Learn how to use headroom wrap and integrate Claude Code, Cursor, and Aider. Route LLM traffic through Headroom's compression pipeline for efficient interaction.

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

---

**`headroom wrap <agent>` starts a local Headroom proxy and patches your agent's configuration so all LLM traffic routes through Headroom's compression pipeline, with optional persistent memory and context-tool injection.**

The `headroom wrap` command in the `chopratejas/headroom` repository is the single entry point for connecting coding assistants to a local Headroom proxy. It handles proxy startup, provider-specific configuration injection, and optional context-tool setup without manual editing of config files. Whether you use Claude Code, Cursor, or Aider, you can integrate token-saving compression with one command.

## What headroom wrap Does Under the Hood

The wrapper is fully **idempotent**. Re-running the same command reuses an already-running proxy, updates the port if you change it, and never duplicates injected configuration blocks.

Three core responsibilities are executed in sequence:

- **Proxy spin-up:** An HTTP server is launched locally (default port 8787) via `_ensure_proxy()` inside [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py). This proxy implements the Headroom compression pipeline.
- **Configuration injection:** The agent's config files are patched so LLM calls point to the proxy instead of the upstream API.
- **Context-tool injection:** By default, either `rtk` (Rust Token Killer) or `lean-ctx` is installed and usage instructions are appended to project-wide agent files such as [`AGENTS.md`](https://github.com/chopratejas/headroom/blob/main/AGENTS.md) or `.cursorrules`.

## headroom wrap Syntax and Flags

The general invocation pattern is:

```bash
headroom wrap <agent> [--port <port>] [--memory] [--no-context-tool] [--] <agent-specific-args>

```

Available flags are:

| Flag | Meaning |
|------|---------|
| `--port` | Custom proxy port (default 8787). |
| `--memory` | Register a persistent **Headroom-Memory MCP** server for cross-session knowledge. |
| `--no-context-tool` | Disable automatic injection of `rtk` or `lean-ctx` shortcuts. |
| `--` | End of Headroom options; everything after is passed verbatim to the wrapped agent. |

You can also set the environment variable `HEADROOM_CONTEXT_TOOL` to `lean-ctx` to use the lean context agent instead of `rtk`. The flag parsing and proxy launch logic lives in **[`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)**.

## Using headroom wrap with Claude Code

Run the following to wrap Claude Code with memory enabled:

```bash
headroom wrap claude --memory

```

When this executes, four things happen:

1. The proxy starts on port 8787 via `_start_proxy`.
2. A **model-provider block** is injected into `~/.codex/config.toml`, setting `model_provider = "headroom"` and overriding `openai_base_url` to point at the proxy. This logic is handled in [`headroom/providers/claude.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/claude.py).
3. If `--memory` is supplied, a **memory-MCP entry** is added to the same TOML file via `_inject_memory_mcp_config`.
4. The chosen context tool (default `rtk`) is installed if missing, and its usage instructions are appended to project agent files via `_inject_rtk_instructions`.

All Claude-specific helper functions, including proxy URL and MCP registration, are defined in **[`headroom/providers/claude.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/claude.py)**, while the generic injection orchestration resides in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py).

## Using headroom wrap with Cursor

Cursor users can run:

```bash
headroom wrap cursor --memory

```

Cursor does not expose a dedicated model-provider hook, so `headroom wrap` appends the **RTK instruction block** directly to `.cursorrules` in the project root. The proxy itself runs identically to the Claude flow.

When `--memory` is used, the Headroom-Memory MCP entry is still written to `~/.codex/config.toml`, making the persistent store available to Cursor-based tools that read that configuration. The Cursor-specific rendering is performed by `_render_cursor_setup_lines` inside **[`headroom/providers/cursor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/cursor.py)**.

## Using headroom wrap with Aider

For Aider, invoke:

```bash
headroom wrap aider --memory

```

The wrapper launches the proxy, then appends the RTK instruction block to [`AGENTS.md`](https://github.com/chopratejas/headroom/blob/main/AGENTS.md) (creating the file if necessary). Because Aider reads [`AGENTS.md`](https://github.com/chopratejas/headroom/blob/main/AGENTS.md) automatically, it picks up the shortcuts without further manual configuration.

Memory MCP registration mirrors the Claude Code path, writing to `~/.codex/config.toml` so Aider can store and retrieve cross-session knowledge. The environment preparation and launch integration for Aider is handled by `headroom.providers.aider.build_launch_env` in **[`headroom/providers/aider.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/aider.py)**.

## Complete Example: Custom Port and Persistent Memory

This example starts the proxy on a non-default port and enables memory for Claude Code:

```bash

# Start the proxy on port 9999 with memory MCP enabled

headroom wrap claude --port 9999 --memory

```

Because the wrapper is idempotent, running the same command again detects the existing proxy and reuses it. It updates the port if changed and avoids duplicating blocks in `~/.codex/config.toml`. Claude Code will now route all LLM calls through `http://127.0.0.1:9999/v1` and use the memory MCP automatically.

## Architecture: How the Pieces Fit Together

The `headroom wrap` orchestration in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py) chains together several internal helpers:

- **`_ensure_proxy()`** — Starts or reuses the local proxy declared in `headroom/cli`.
- **`_inject_*_provider_config()`** — Injects Claude-specific TOML overrides into `~/.codex/config.toml`.
- **`_inject_rtk_instructions()`** — Appends the context-tool instruction block to files like [`AGENTS.md`](https://github.com/chopratejas/headroom/blob/main/AGENTS.md) or `.cursorrules`.
- **`_inject_memory_mcp_config()`** — Optionally registers the Headroom-Memory MCP server.

The proxy itself runs the full Headroom transform pipeline (CacheAligner → ContentRouter → SmartCrusher). You can find the algorithmic implementation under **`headroom/transforms/`** in the repository.

## Summary

- **`headroom wrap <agent>`** is the single command needed to integrate Claude Code, Cursor, or Aider with the Headroom compression proxy.
- It is fully **idempotent**: safe to run multiple times without duplicating configuration.
- Under the hood, it launches a proxy via `_ensure_proxy()`, patches agent configs, and optionally installs a context tool (`rtk` or `lean-ctx`) plus the Memory MCP server.
- Key source files include **[`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)** for orchestration, **[`headroom/providers/claude.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/claude.py)**, **[`cursor.py`](https://github.com/chopratejas/headroom/blob/main/cursor.py)**, and **[`aider.py`](https://github.com/chopratejas/headroom/blob/main/aider.py)** for agent-specific logic, and **`headroom/transforms/`** for the core pipeline.

## Frequently Asked Questions

### What does headroom wrap do exactly?

`headroom wrap` starts a local HTTP proxy and reconfigures your coding agent to send LLM requests through it. It also optionally injects a context tool and registers a memory MCP server so the agent can use Headroom's compression and persistent knowledge features.

### Can I run headroom wrap multiple times safely?

Yes. The wrapper is designed to be idempotent. Re-running the same command will reuse an already-running proxy, update the port if you specify a new one, and will not duplicate injected configuration blocks in your agent's files.

### How do I switch from rtk to lean-ctx?

Set the `HEADROOM_CONTEXT_TOOL` environment variable to `lean-ctx` before running the wrap command. For example, `export HEADROOM_CONTEXT_TOOL=lean-ctx` followed by `headroom wrap cursor` will install the lean context agent instead of the default `rtk` tool.

### Which agents are supported by headroom wrap?

The CLI supports Claude Code, Cursor, Aider, and other agents listed in the `headroom wrap` help. Each agent has its own provider module under **`headroom/providers/`**, such as [`claude.py`](https://github.com/chopratejas/headroom/blob/main/claude.py), [`cursor.py`](https://github.com/chopratejas/headroom/blob/main/cursor.py), and [`aider.py`](https://github.com/chopratejas/headroom/blob/main/aider.py), which handles the specific configuration format that agent expects.