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

> Learn how to wrap AI code assistants like Copilot with headroom wrap. Streamline your AI coding workflow by routing API traffic through Headroom's compression pipeline. Get started now.

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

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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:

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

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

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

```bash
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`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py)** – Implements the `headroom wrap` command group, parses options, and orchestrates the proxy startup and binary execution
- **[`headroom/copilot_auth.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py)** and **[`headroom/transforms/code_compressor.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.