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

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. 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 or .cursorrules.

headroom wrap Syntax and Flags

The general invocation pattern is:

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.

Using headroom wrap with Claude Code

Run the following to wrap Claude Code with memory enabled:

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.
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, while the generic injection orchestration resides in headroom/cli/wrap.py.

Using headroom wrap with Cursor

Cursor users can run:

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.

Using headroom wrap with Aider

For Aider, invoke:

headroom wrap aider --memory

The wrapper launches the proxy, then appends the RTK instruction block to AGENTS.md (creating the file if necessary). Because Aider reads 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.

Complete Example: Custom Port and Persistent Memory

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

# 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 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 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 for orchestration, headroom/providers/claude.py, cursor.py, and 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, cursor.py, and aider.py, which handles the specific configuration format that agent expects.

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