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

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.

Wrapping Claude Code for Context Compression

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

headroom wrap claude

This command performs several actions defined in 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 to download and verify the binary.

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

{
  "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 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:

headroom wrap cursor

The implementation relies on render_setup_lines in headroom/providers/cursor/__init__.py to generate the appropriate syntax. The command prints a setup block similar to:

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

headroom wrap aider

The wrapper executes _build_aider_launch_env from 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 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:

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 (lines 53–71).

4. Inject Configuration – Agent-specific callbacks print configuration snippets. For example, Claude Code receives JSON for settings.json, while Cursor receives rules for .cursorrules. The code also writes "RTK instructions" to 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, 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 and 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, headroom/providers/cursor/__init__.py, and 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 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 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.

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