How the Headroom Wrap Command Works with Claude Code, Codex, Cursor, and Other Agents

The headroom wrap command transforms standard LLM agent CLI sessions into Headroom-enabled pipelines by launching a local proxy and injecting agent-specific configuration, enabling transparent context compression and routing without modifying client source code.

The headroom wrap command is the primary entry point in the chopratejas/headroom repository for integrating popular AI coding agents with the Headroom optimization layer. It intercepts outbound LLM traffic from tools like Claude Code, Codex, and Cursor by dynamically rewriting their configuration to point at a local proxy. Once wrapped, every request benefits from Headroom's context-tool compression and optional MCP tooling.

What the headroom wrap Command Actually Does

When you run headroom wrap <agent>, the orchestration logic in headroom/cli/wrap.py performs a coordinated sequence of setup steps:

• Parse the agent name. The Click sub-command records the requested agent—such as claude, codex, or cursor—and dispatches to the appropriate provider logic. (See headroom/cli/wrap.py, lines 4–12.)

• Select and install a context tool. By default, Headroom installs the Rust Token Killer (rtk). You can switch to the lean-ctx helper by setting the HEADROOM_CONTEXT_TOOL environment variable. (See _selected_context_tool_, _setup_rtk_, and _setup_lean_ctx_agent_ in headroom/cli/wrap.py, lines 81–115.)

• Start the Headroom proxy. A background uvicorn process is launched on a free localhost port (or a user-specified one). The proxy handles cache alignment, content routing, compression, and MCP registration. (See _ensure_proxy_ and _start_proxy_ in headroom/cli/wrap.py, lines 58–66.)

• Inject agent-specific configuration. Headroom writes the files each client expects—such as ~/.codex/config.toml for Codex or ~/.claude/settings.json for Claude—to point at the local proxy. (See _inject_codex_provider_config_ in headroom/cli/wrap.py, lines 818–842.)

• Register MCP tools (optional). For agents that support the Model Context Protocol, Headroom registers a retrieve-tool server so the LLM can request extra data like code-graph queries. (See _register_cbm_mcp_server_ in headroom/cli/wrap.py, lines 410–424.)

• Print setup instructions and block. For proxy-only agents, the CLI prints the required environment variables and waits until Ctrl-C before shutting down cleanly. (See _run_proxy_only_watcher_ in headroom/cli/wrap.py, lines 430–470.)

Agent-Specific Wrapping Details

Every supported client follows the same proxy lifecycle, but the specific injection strategy varies. The modular architecture in headroom/cli/wrap.py means adding a new agent only requires specifying which config files to touch and whether the agent launches as a child process or runs in proxy-only mode.

Claude Code (headroom wrap claude)

For Claude Code, Headroom registers an rtk PreToolUse hook by running rtk init --global --auto-patch. This hook executes rtk rewrite before each tool use, and it is automatically removed when you run headroom unwrap claude. (Implementation: _remove_claude_rtk_hooks_ in headroom/cli/wrap.py, lines 57–70.)

Headroom also registers a code-graph MCP server via _register_cbm_mcp_server_. Once active, Claude can call /mcp tools such as code_graph or memory_search to enrich its context dynamically. (Implementation: headroom/cli/wrap.py, lines 410–424.)

OpenAI Codex (headroom wrap codex)

Codex is wrapped by injecting a small TOML block into ~/.codex/config.toml that forces the client to use http://127.0.0.1:<port>/v1 and sets model_provider = "headroom". All subsequent codex commands then route through the Headroom proxy automatically. (Implementation: _inject_codex_provider_config_ in headroom/cli/wrap.py, lines 818–842.)

When the --memory flag is passed, Headroom also appends the "code-graph" MCP server to Codex’s configuration so the agent can perform retrieval-augmented queries. (Implementation: _inject_memory_mcp_config_ in headroom/cli/wrap.py, lines 1089–1112.)

Cursor (headroom wrap cursor)

Cursor operates in proxy-only mode. Because Cursor cannot be launched as a child process, headroom wrap cursor simply starts the proxy, prints an export HEADROOM_PROXY=http://127.0.0.1:<port> line, and blocks until you press Ctrl-C. (Implementation: _run_proxy_only_watcher_ in headroom/cli/wrap.py, lines 430–470; setup-line rendering in headroom/providers/cursor/wrap.py.)

In addition, Headroom appends the rtk instruction block (RTK_INSTRUCTIONS_BLOCK) to ~/.cursorrules so that Cursor’s shell-aware prompts are compressed before being sent. (Implementation: _inject_rtk_instructions_ in headroom/cli/wrap.py, lines 885–906.)

Other Agents: Copilot, Aider, and OpenClaw

• Copilot – headroom wrap copilot resolves the Copilot OAuth token and forwards it to the proxy as GITHUB_COPILOT_API_TOKEN. If you pass --backend anyllm, it also injects a BYOK provider configuration. (Key code: headroom/providers/copilot/wrap.py and _resolve_copilot_provider_type_ in headroom/cli/wrap.py, lines 1277–1280.)

• Aider – The wrapper spawns Aider as a child process after the proxy is online, passing the proxy URL through the HEADROOM_PROXY environment variable. No local config files are modified. (Key code: headroom/providers/aider/wrap.py.)

• OpenClaw – Headroom installs the headroom-openclaw plugin, writes a JSON gateway entry pointing at the proxy, and registers the MCP server for OpenClaw’s toolchain. (Key code: headroom/providers/openclaw/wrap.py.)

Practical Usage Examples

You can wrap an agent in a single terminal command. All commands are idempotent, so re-running them safely refreshes the proxy port and configuration.

Start a Claude Code session with rtk hooks and MCP tooling:

headroom wrap claude

This launches the proxy on the default port (8787), installs rtk at ~/.headroom/rtk/rtk, and injects the hook into ~/.claude/settings.json.

Run a wrapped Codex session with automatic provider injection:

headroom wrap codex
codex <your-prompt>

Codex now reads ~/.codex/config.toml and routes every request through the local Headroom proxy.

Keep the proxy alive for Cursor and print the required export:

headroom wrap cursor

The CLI prints:

export HEADROOM_PROXY=http://127.0.0.1:8787

Press Ctrl-C to stop the proxy when you are done.

Wrap Copilot with a custom backend model:

headroom wrap copilot -- --model claude-sonnet-4-20250514

Install the OpenClaw plugin and register the MCP server:

headroom wrap openclaw

Core Source Files and Architecture

The wrapping pipeline is centralized in headroom/cli/wrap.py, which delegates provider-specific logic to small modular wrappers under headroom/providers/. The following files control exactly how each agent is instrumented:

• headroom/cli/wrap.py – Central orchestration, proxy lifecycle (_ensure_proxy_, _start_proxy_), and configuration injection.
• headroom/providers/claude/__init__.py – Defines the base proxy URL for Claude integration.
• headroom/providers/codex/wrap.py – Builds the launch environment and TOML overrides for Codex.
• headroom/providers/cursor/wrap.py – Generates proxy-only setup lines for Cursor.
• headroom/providers/copilot/wrap.py – Handles OAuth token resolution and BYOK provider setup.
• headroom/providers/aider/wrap.py – Spawns Aider with the correct HEADROOM_PROXY variable.
• headroom/providers/openclaw/wrap.py – Manages plugin installation and JSON gateway entries.
• headroom/rtk/installer.py – Downloads and installs the default rtk context tool.
• headroom/lean_ctx/installer.py – Downloads the optional lean-ctx context tool.
• headroom/mcp_registry/ – Contains MCP registration utilities shared across Claude, Codex, and OpenClaw.

Summary

• The headroom wrap command launches a local uvicorn proxy and installs a context tool (rtk by default) to compress LLM context before it leaves your machine.
• Claude Code receives rtk PreToolUse hooks and optional MCP servers for code-graph queries.
• OpenAI Codex gets a TOML provider override in ~/.codex/config.toml that transparently routes requests to the Headroom proxy.
• Cursor runs in proxy-only mode; you export HEADROOM_PROXY manually and Headroom injects compression instructions into ~/.cursorrules.
• Copilot, Aider, and OpenClaw each have dedicated wrappers that handle OAuth tokens, child-process spawning, or plugin installation without touching unrelated config files.
• All wrap operations are idempotent and share the same proxy lifecycle defined in headroom/cli/wrap.py.

Frequently Asked Questions

What does the headroom wrap command actually do?

It launches a local proxy on a free localhost port and rewrites agent-specific configuration so that outbound LLM requests flow through Headroom’s compression and routing pipeline. The command handles everything from context-tool installation to MCP registration without requiring changes to the agent’s source code.

How does headroom wrap claude differ from headroom wrap cursor?

headroom wrap claude installs an rtk PreToolUse hook inside ~/.claude/settings.json and registers a code-graph MCP server. By contrast, headroom wrap cursor cannot launch Cursor as a child process, so it simply starts the proxy, injects instructions into ~/.cursorrules, and prints an export HEADROOM_PROXY line for manual configuration.

Is it safe to run the headroom wrap command multiple times?

Yes. The implementation in headroom/cli/wrap.py is designed to be idempotent. Re-running the command updates the proxy port and refreshes configuration entries without corrupting or duplicating existing files.

Which agents support MCP tool registration through Headroom?

According to the source code in headroom/cli/wrap.py, Claude Code and OpenAI Codex both support MCP registration via _register_cbm_mcp_server_ and _inject_memory_mcp_config_. These functions expose tools such as code_graph and memory_search so the LLM can request additional context dynamically.

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