# How to Wrap Existing Coding Agents with Headroom: A Complete Guide > Learn how to wrap existing coding agents with Headroom using the simple headroom wrap command. This guide explains the process and benefits of using Headroom's proxy for code agents. - Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom) - Tags: how-to-guide - Published: 2026-06-12 --- **Headroom provides a single entry point—`headroom wrap `—that launches a local proxy, optionally installs a context‑tool, and configures the target coding agent to route all its requests through the proxy.** The `chopratejas/headroom` repository delivers a seamless integration layer for AI coding assistants. When you **wrap existing coding agents with Headroom**, you intercept all LLM traffic through a local compression proxy without modifying the agent's underlying source code. ## The Three-Stage Wrapping Process The wrapper operates through a coordinated pipeline defined in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py). Each execution flows through three distinct stages to ensure minimal setup friction and maximum token savings. ### Stage 1: Proxy Startup The `_start_proxy_` function (lines 98–115) spawns a background `headroom proxy` process on a configurable port. This proxy intercepts every payload—including tool outputs, logs, RAG chunks, and file contents—before transmission to the LLM. The compression pipeline follows the **ContentRouter** → **SmartCrusher / CodeCompressor / Kompress‑base** architecture, reducing token counts transparently. ### Stage 2: Context-Tool Injection Depending on the `HEADROOM_CONTEXT_TOOL` environment variable (defaulting to `rtk` with `lean-ctx` as an alternative), the `_setup_context_tool_for_agent_` function (lines 163–191) installs the appropriate binary. When set to `rtk`, Headroom downloads the **Rust Token Killer** binary via [`headroom/rtk/installer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/rtk/installer.py). The `lean-ctx` alternative triggers the setup script in [`headroom/lean_ctx/installer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/lean_ctx/installer.py). These tools inject token‑saving instructions directly into the agent's configuration files. ### Stage 3: Agent-Specific Configuration Each supported agent implements a provider-specific wrapper that rewrites configuration files or injects environment variables. The [`headroom/proxy/project_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/project_context.py) module adds per-project tracking through the `X‑Headroom‑Project` header, enabling fine-grained savings analytics across different codebases. ## Supported Agents and Configuration Details Headroom currently supports Claude Code, Codex, Cursor, and GitHub Copilot CLI, each with specialized handling in the `headroom/providers/` directory. **Claude Code**: The wrapper passes the proxy URL via `HEADROOM_AGENT_TYPE` and enriches `ANTHROPIC_CUSTOM_HEADERS` with project metadata. The `_apply_project_header_env` function (lines 78–102) in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py) manages this injection, while [`headroom/providers/claude/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/claude/__init__.py) handles the underlying environment tweaks. **Codex**: Running `headroom wrap codex` triggers `_inject_codex_provider_config` (lines 104–124) to insert a Headroom model provider block into `~/.codex/config.toml`. This redirects Codex's LLM requests through the local proxy without manual file editing. **Cursor**: The Cursor provider in [`headroom/providers/cursor/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/cursor/__init__.py) generates configuration instructions based on the selected `HEADROOM_CONTEXT_TOOL`, outputting the necessary setup steps for the Cursor IDE. **GitHub Copilot CLI**: The `_build_copilot_launch_env` function in [`headroom/providers/copilot/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/copilot/__init__.py) discovers the Copilot authentication token, resolves the correct API endpoint, and patches the environment with `GITHUB_COPILOT_API_TOKEN` before launching the CLI. ## Installing Headroom and Basic Usage Install Headroom via Python pip or Node npm: ```bash # Python installation pip install "headroom-ai[all]" # Node / TypeScript installation npm install headroom-ai ``` Wrap your preferred coding agent using the CLI: ```bash # Wrap Claude Code with default RTK context tool headroom wrap claude # Wrap Codex with proxy provider injection headroom wrap codex # Wrap Cursor (prints configuration instructions) headroom wrap cursor # Wrap GitHub Copilot CLI with specific model headroom wrap copilot -- --model gpt-4o # Wrap arbitrary agent with custom port and memory headroom wrap coder --port 9999 --memory ``` Typical output after wrapping Claude Code: ``` Starting proxy on port 8787 … Logs: /home/user/.headroom/logs/proxy.log Injecting rtk instructions into AGENTS.md … HEADROOM WRAP: CLAUDE Press Ctrl+C to stop the proxy. ``` ## Idempotency and Unwrapping The wrapping process is **idempotent**. HTML-style markers like `` prevent duplicate injections, ensuring repeated runs do not corrupt configuration files. Before modification, Headroom creates snapshots such as `config.toml.headroom-backup` to preserve the original state. To restore an agent to its pre-wrapped configuration: ```bash headroom unwrap claude ``` This command reverses all modifications, removes proxy settings, and deletes injected context-tool instructions. ## Summary - **Single command integration**: Use `headroom wrap ` to proxy-enable any supported coding agent without source code changes. - **Three-stage pipeline**: Proxy startup (`_start_proxy_`), context-tool installation (`_setup_context_tool_for_agent_`), and agent-specific configuration rewriting. - **Automatic compression**: All traffic routes through the ContentRouter → SmartCrusher pipeline for transparent token reduction. - **Safe and reversible**: Idempotent injections with marker comments and automatic backups ensure clean `headroom unwrap` restoration. - **Multi-agent support**: Native providers for Claude Code, Codex, Cursor, and Copilot CLI with environment-specific optimizations. ## Frequently Asked Questions ### Does wrapping an agent modify its source code? No. Headroom operates exclusively through configuration file injection and environment variable manipulation. The wrappers in `headroom/providers/` rewrite configs like `~/.codex/config.toml` or set variables like `ANTHROPIC_CUSTOM_HEADERS`, leaving the original agent binaries untouched. ### What happens if the proxy fails or the port is blocked? The `_start_proxy_` function in [`headroom/cli/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py) handles port allocation and logging to `~/.headroom/logs/proxy.log`. If the proxy cannot start, the wrap command exits with an error before modifying any agent configuration, preventing partial or broken setups. ### Can I use Headroom with a custom or unsupported coding agent? Yes. While Headroom provides optimized wrappers for Claude, Codex, Cursor, and Copilot, you can wrap arbitrary agents by specifying a custom port: `headroom wrap --port 9999`. You must manually configure the agent to use `http://localhost:9999` as its API endpoint. ### How does the context tool selection affect token savings? The `HEADROOM_CONTEXT_TOOL` environment variable selects between `rtk` (Rust Token Killer) and `lean-ctx`. The RTK binary provides aggressive token compression through [`headroom/rtk/installer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/rtk/installer.py), while `lean-ctx` offers a lightweight alternative via [`headroom/lean_ctx/installer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/lean_ctx/installer.py). Both inject instructions that reduce context window usage before payloads reach the LLM.