How to Wrap Existing Coding Agents with Headroom: A Complete Guide

Headroom provides a single entry point—headroom wrap <agent>—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. 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. The lean-ctx alternative triggers the setup script in 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 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 manages this injection, while 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 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 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:

# Python installation

pip install "headroom-ai[all]"

# Node / TypeScript installation  

npm install headroom-ai

Wrap your preferred coding agent using the CLI:

# 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 <!-- headroom:rtk-instructions --> 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:

headroom unwrap claude

This command reverses all modifications, removes proxy settings, and deletes injected context-tool instructions.

Summary

• Single command integration: Use headroom wrap <agent> 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 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 <custom-agent> --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, while lean-ctx offers a lightweight alternative via headroom/lean_ctx/installer.py. Both inject instructions that reduce context window usage before payloads reach the LLM.

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