# How to Wrap Claude Code, Cursor, or Aider with Headroom for Compression

> Learn to wrap Claude Code Cursor or Aider with Headroom. Reduce token usage by 60-95% with this single-command local proxy solution, no agent source code modification needed.

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

---

**Headroom provides a single-command wrapper that launches a local proxy and injects context-tools to route Claude Code, Cursor, and Aider traffic through compression pipelines, reducing token usage by 60–95% without modifying agent source code.**

The `chopratejas/headroom` repository eliminates the friction of manually configuring LLM proxies for AI coding assistants. By running `headroom wrap <agent>`, you activate a local proxy on port 8787 and automatically inject context-aware binaries like RTK or lean-ctx. This article explains the exact mechanics of how to wrap Claude Code, Cursor, or Aider with Headroom for compression using the implementation in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py).

## Wrapping Claude Code for Context Compression

To compress Claude Code conversations, run the dedicated wrapper command:

```bash
headroom wrap claude

```

This command performs several actions defined in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py). It first prints a centered banner via `_print_wrap_banner` to confirm the target agent, then launches the Headroom proxy in the background using `_ensure_proxy`. The proxy spins up on localhost port 8787 (configurable) and writes logs to `~/.headroom/logs/proxy.log`.

The wrapper then checks the `HEADROOM_CONTEXT_TOOL` environment variable (defaulting to `rtk`) through `_selected_context_tool`. If RTK is selected, the code calls `_ensure_rtk_binary` from [`headroom/rtk/installer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/rtk/installer.py) to download and verify the binary.

Finally, the wrapper prints a JSON configuration snippet for Claude Code:

```json
{
  "hooks": [
    {
      "type": "pre_tool_use",
      "command": "<rtk-binary> rewrite"
    }
  ]
}

```

Copy this snippet into `~/.claude/settings.json`. The wrapper also writes RTK instruction blocks to [`AGENTS.md`](https://github.com/chopratejas/headroom/blob/main/AGENTS.md) in your project root, ensuring the LLM uses the `rtk` prefix for shell commands. To skip RTK installation, append `--no-context-tool` to the wrap command.

## Wrapping Cursor with Headroom Compression

For Cursor, the wrapper generates configuration lines compatible with the `.cursorrules` file:

```bash
headroom wrap cursor

```

The implementation relies on `render_setup_lines` in [`headroom/providers/cursor/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/cursor/__init__.py) to generate the appropriate syntax. The command prints a setup block similar to:

```text

# headroom:rtk-instructions

# (RTK block automatically injected by Headroom)

```

Paste this block into your `~/.cursorrules` file. As with Claude Code, the wrapper starts the local proxy on port 8787 and handles binary installation. The Cursor-specific provider logic ensures the generated instructions match Cursor’s expected formatting for system prompts.

## Wrapping Aider with Automatic Proxy Configuration

Aider requires no manual configuration file editing. When you run:

```bash
headroom wrap aider

```

The wrapper executes `_build_aider_launch_env` from [`headroom/providers/aider/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/aider/__init__.py) to construct the proper environment variables. It then launches Aider as a child process with `HEADROOM_AGENT_TYPE=aider` set, automatically routing all tool calls through the Headroom proxy.

Because the wrapper manages the subprocess directly, Aider inherits the proxy settings without requiring changes to [`.aider.conf.yml`](https://github.com/chopratejas/headroom/blob/main/.aider.conf.yml) or environment exports in your shell profile. The proxy compresses both the prompts sent to the LLM and the responses returned to the agent.

## How the Wrap Command Works Internally

The `headroom wrap` functionality follows a strict five-step pipeline implemented in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py):

1. **Display Banner** – The `_print_wrap_banner` function draws a centered heading so users immediately see which agent is being wrapped (lines 16–32).

2. **Start Local Proxy** – The `_ensure_proxy` helper launches `headroom cli proxy` as a background subprocess on a free localhost port (default 8787), redirecting stdout and stderr to `~/.headroom/logs/proxy.log` (lines 33–41).

3. **Select Context Tool** – The `_selected_context_tool` function reads `HEADROOM_CONTEXT_TOOL` (default `rtk`) and dispatches to either `_setup_lean_ctx_agent` or `_ensure_rtk_binary`. For lean-ctx selection, it downloads binaries via [`headroom/lean_ctx/installer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/lean_ctx/installer.py) (lines 53–71).

4. **Inject Configuration** – Agent-specific callbacks print configuration snippets. For example, Claude Code receives JSON for [`settings.json`](https://github.com/chopratejas/headroom/blob/main/settings.json), while Cursor receives rules for `.cursorrules`. The code also writes "RTK instructions" to [`AGENTS.md`](https://github.com/chopratejas/headroom/blob/main/AGENTS.md) to prefix shell commands with `rtk` (lines 88–100).

5. **Install Optional Services** – For agents supporting extended memory or code-graph features, the wrapper calls `_setup_code_graph` and `_setup_headroom_mcp` to register MCP servers.

The actual compression logic resides in [`headroom/cli/proxy.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/proxy.py), which implements the SmartCrusher, CodeCompressor, and Kompress-base pipelines. Because the proxy runs locally, it preserves privacy and remains fully reversible—simply stop the proxy process to return to direct LLM connections.

## Summary

- **Single-command setup**: Run `headroom wrap claude`, `headroom wrap cursor`, or `headroom wrap aider` to initialize compression for your preferred agent.
- **Local proxy architecture**: The wrapper starts a proxy on port 8787 via `_ensure_proxy`, logging to `~/.headroom/logs/proxy.log` without exposing data to external services.
- **Automatic binary management**: The code handles RTK and lean-ctx installation through [`headroom/rtk/installer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/rtk/installer.py) and [`headroom/lean_ctx/installer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/lean_ctx/installer.py) based on the `HEADROOM_CONTEXT_TOOL` environment variable.
- **Zero source modifications**: Agents connect to the local proxy through configuration snippets (JSON for Claude Code, `.cursorrules` for Cursor) or inherited environment variables (Aider).
- **Provider-specific logic**: [`headroom/providers/claude/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/claude/__init__.py), [`headroom/providers/cursor/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/cursor/__init__.py), and [`headroom/providers/aider/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/aider/__init__.py) contain the agent-specific glue code.

## Frequently Asked Questions

### Do I need to modify Claude Code's source code to use Headroom?

No. Headroom operates as a transparent wrapper. The `headroom wrap claude` command generates a JSON snippet for `~/.claude/settings.json` that points Claude Code to the local proxy. The source files in `chopratejas/headroom` remain untouched, and you can revert changes by removing the proxy configuration.

### Which context tool does Headroom use by default?

Headroom defaults to **RTK** (Rust Tool Kit). The `_selected_context_tool` function in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py) checks the `HEADROOM_CONTEXT_TOOL` environment variable, defaulting to `rtk` if unset. You can switch to lean-ctx by setting `HEADROOM_CONTEXT_TOOL=lean-ctx` before running the wrap command.

### Can I run the Headroom proxy on a different port?

Yes. While the default port is 8787, you can configure this through Headroom's settings. The `_ensure_proxy` function in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py) handles port allocation and will use your specified configuration when launching the background subprocess.

### Is the compression setup reversible?

Yes. The wrap command is completely non-destructive. Since the proxy runs locally and only modifies agent configuration files (like `~/.claude/settings.json` or `~/.cursorrules`), you can stop using Headroom by killing the proxy process and removing the configuration snippets. The original agent behavior remains intact.