How to Wrap AI Code Assistants Like Copilot with `headroom wrap`

To wrap GitHub Copilot with Headroom, run headroom wrap copilot -- --model <model>, which starts a local proxy, injects the required environment variables, and launches the Copilot CLI so all API traffic routes through Headroom's compression pipeline.

The chopratejas/headroom repository provides an open-source compression proxy that reduces token usage for LLM-powered coding assistants. Learning how to wrap AI code assistants like Copilot with headroom wrap enables you to reduce API costs by approximately 90% while maintaining full compatibility with existing workflows. This guide explains the internal mechanics, source code implementation, and practical commands for routing GitHub Copilot traffic through the Headroom proxy.

What headroom wrap Does for Copilot

headroom wrap is a convenience frontend that automates three critical tasks: starting a Headroom proxy, configuring environment variables to intercept API calls, and launching the target AI-assistant binary. When you wrap Copilot, all outbound requests to OpenAI-compatible endpoints are automatically routed through Headroom's local server, which runs the CacheAligner → ContentRouter → Compressor pipeline before forwarding traffic to the LLM provider.

Step-by-Step Execution Flow

The wrapping process follows a strict sequence implemented in the CLI layer and authentication modules.

CLI Parsing and Command Registration

The wrap command is defined in headroom/cli/wrap.py (lines 33-45), where it registers sub-commands for each supported assistant including Copilot, Claude Code, and Codex. The parser distinguishes between wrap semantics (launching a managed process) and proxy semantics (running a standalone server).

Proxy Startup

Upon invocation, headroom wrap copilot calls the shared helper _start_proxy(port, …) to instantiate a local server. By default, this proxy binds to port 8787 and listens for any OpenAI-compatible request (see headroom/cli/wrap.py, lines 55-61). The proxy remains active for the duration of the wrapped session.

Environment Variable Injection

Before executing the Copilot binary, the wrapper prepares the execution environment:

• Sets OPENAI_BASE_URL (or ANTHROPIC_BASE_URL for Claude) to point at http://127.0.0.1:8787/v1
• Sets COPILOT_PROVIDER_API_URL when the --subscription flag targets GitHub Copilot's upstream
• Prepares authentication headers via the Copilot auth helper in headroom/copilot_auth.py, which resolves a reusable OAuth token or falls back to a generic GitHub token

Token Exchange for Subscription Mode

If you invoke the wrapper with --subscription, Headroom executes a token-exchange flow:

1. The helper copilot_auth.apply_copilot_api_auth adds a Bearer header to outbound Copilot requests (verified in tests/test_proxy_copilot_auth_hooks.py, lines 79-99)
2. The exchange contacts https://api.githubcopilot.com (or a custom enterprise endpoint) to obtain a short-lived Copilot token
3. The token is cached for the session and injected into subsequent API calls

Assistant CLI Execution

After the proxy is initialized and the environment is configured, headroom wrap uses exec to replace itself with the target binary (e.g., copilot), passing any arguments specified after the -- separator. The assistant process now communicates exclusively with the local Headroom proxy, enabling features like reversible compression (CCR) and cross-assistant memory sharing through the local cache.

Practical Code Examples

Basic Copilot Wrapping

Start a Headroom proxy and launch Copilot with the default compression settings:

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

This sequence:

• Starts headroom proxy --port 8787 automatically
• Exports OPENAI_BASE_URL=http://127.0.0.1:8787/v1
• Executes copilot with the remaining CLI arguments (--model …)

Subscription Mode with Token Exchange

For paid Copilot tiers that require OAuth token exchange:

headroom wrap copilot --subscription -- --model gpt-4o

This triggers:

• Execution of copilot_auth.resolve_subscription_bearer_token() to obtain a valid token
• Configuration of COPILOT_PROVIDER_API_URL pointing at https://api.githubcopilot.com
• Automatic injection of Authorization: Bearer <token> headers on every request

Programmatic Proxy Usage from Python

If you need to integrate Headroom into a custom script:

import os
import subprocess

# Start the Headroom proxy in the background

subprocess.Popen(["headroom", "proxy", "--port", "8787"])

# Point the OpenAI client at the proxy

os.environ["OPENAI_BASE_URL"] = "http://127.0.0.1:8787/v1"

# All subsequent calls go through Headroom's compression pipeline

from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain quicksort"}],
)
print(response)

Enabling Persistent Memory

To maintain cross-session context across multiple Copilot conversations:

headroom wrap copilot --memory -- --model gpt-4o

This creates a .headroom/memory.db file that syncs with the Copilot process, enabling the proxy to reference previous interactions in subsequent sessions.

Key Source Files and Implementation Details

Understanding the following files helps when debugging or extending the wrapping functionality:

• headroom/cli/wrap.py – Implements the headroom wrap command group, parses options, and orchestrates the proxy startup and binary execution
• headroom/copilot_auth.py – Handles OAuth token discovery, the token-exchange flow, and injection of the Authorization header for Copilot subscription mode
• tests/test_proxy_copilot_auth_hooks.py – Unit tests verifying that the auth hook correctly adds headers to Copilot requests (see lines 79-99 for the validation logic)
• headroom/transforms/smart_crusher.py and headroom/transforms/code_compressor.py – Core compression transforms that run inside the proxy for all wrapped assistants

Summary

• headroom wrap copilot is the zero-code integration method for routing Copilot API traffic through Headroom's compression pipeline
• The wrapper automatically handles proxy startup, environment configuration, and token exchange for subscription mode
• All requests pass through the CacheAligner → ContentRouter → Compressor chain, reducing token usage by approximately 90%
• Original payloads are cached locally, enabling reversible compression and cross-assistant memory sharing when using flags like --memory

Frequently Asked Questions

What is the difference between headroom wrap and headroom proxy?

headroom wrap is a lifecycle manager that starts a proxy, configures environment variables, and launches the target assistant binary as a child process. headroom proxy runs only the HTTP server component without managing external processes. Use wrap for convenience when you want Headroom to handle the entire execution context; use proxy when you need manual control over the client configuration.

How does Headroom handle authentication for GitHub Copilot?

Headroom utilizes the copilot_auth.py module to resolve OAuth tokens. In subscription mode, it performs a token exchange with GitHub's authentication servers to obtain a short-lived Bearer token, which is then cached and injected into the Authorization header of every request. This eliminates the need to manually extract or configure GitHub tokens.

Can I use headroom wrap with assistants other than Copilot?

Yes. The headroom/cli/wrap.py implementation registers sub-commands for multiple assistants including Claude Code and OpenAI Codex. Each assistant receives the appropriate base URL configuration (e.g., ANTHROPIC_BASE_URL for Claude) while sharing the same compression pipeline and proxy infrastructure.

Does wrapping Copilot require modifying my existing code?

No. The wrapping mechanism is non-invasive. headroom wrap uses environment variable injection and process execution to intercept traffic without requiring changes to your Copilot installation or workflow. You simply prepend headroom wrap copilot to your normal command, and the wrapper handles the interception transparently.

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