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

> Discover how the headroom wrap command enhances Claude Code, Codex, Cursor and other agents. Learn to transform CLI sessions into pipelines with transparent context compression and routing.

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

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py), lines 430–470; setup-line rendering in [`headroom/providers/cursor/wrap.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/copilot/wrap.py) and `_resolve_copilot_provider_type_` in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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:

```bash
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:

```bash
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:

```bash
headroom wrap cursor

```

The CLI prints:

```bash
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:

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

```

Install the OpenClaw plugin and register the MCP server:

```bash
headroom wrap openclaw

```

## Core Source Files and Architecture

The wrapping pipeline is centralized in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py) – Central orchestration, proxy lifecycle (`_ensure_proxy_`, `_start_proxy_`), and configuration injection.
- [`headroom/providers/claude/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/claude/__init__.py) – Defines the base proxy URL for Claude integration.
- [`headroom/providers/codex/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/codex/wrap.py) – Builds the launch environment and TOML overrides for Codex.
- [`headroom/providers/cursor/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/cursor/wrap.py) – Generates proxy-only setup lines for Cursor.
- [`headroom/providers/copilot/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/copilot/wrap.py) – Handles OAuth token resolution and BYOK provider setup.
- [`headroom/providers/aider/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/aider/wrap.py) – Spawns Aider with the correct `HEADROOM_PROXY` variable.
- [`headroom/providers/openclaw/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/openclaw/wrap.py) – Manages plugin installation and JSON gateway entries.
- [`headroom/rtk/installer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/rtk/installer.py) – Downloads and installs the default `rtk` context tool.
- [`headroom/lean_ctx/installer.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.