Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/headroomlabs-ai/headroom/llms.txt

Use this file to discover all available pages before exploring further.

headroom wrap <tool> is the fastest way to connect any supported AI coding agent to Headroom. It starts the proxy as a background process, configures the agent to route through it, installs the MCP retrieve tool and context tools (rtk or lean-ctx), then launches the agent — all in a single command. 
headroom wrap claude          # Start proxy + context tool + Claude Code
headroom wrap codex           # Start proxy + OpenAI Codex CLI
headroom wrap cursor          # Start proxy + print Cursor setup instructions
headroom wrap copilot         # Start proxy + GitHub Copilot CLI
headroom wrap aider           # Start proxy + aider
headroom wrap goose           # Start proxy + Block Goose
headroom wrap openhands       # Start proxy + OpenHands
headroom wrap cline           # Start proxy + Cline (print instructions)
headroom wrap continue        # Start proxy + Continue (print instructions)
headroom wrap vibe            # Start proxy + Mistral Vibe CLI
headroom wrap opencode        # Start proxy + OpenCode
headroom wrap openclaw        # Install + configure OpenClaw plugin
headroom unwrap <tool> reverses the configuration — restoring original settings and optionally stopping the local proxy.

​
Supported tools

ToolLaunch typeDurable unwrap
claudeLaunches binary✓
codexLaunches binary✓
cursorPrints config instructions—
aiderLaunches binary—
copilotLaunches binary✓
clinePrints config instructions—
continuePrints config instructions—
gooseLaunches binary—
openhandsSets env variables—
opencodeLaunches binary✓
openclawPlugin install✓
vibeLaunches binary—

​
Common flags

These flags are accepted by most or all wrap subcommands.
​
--port / -p
integer
default:"8787"
Proxy port to start on (or connect to if --no-proxy is set).
​
--no-context-tool
flag
Skip rtk / lean-ctx context-tool setup. Compression and MCP still work; the agent just won’t have the token-optimized shell command wrapper.
​
--memory
flag
Enable persistent cross-session memory in the proxy. Memories are automatically saved and retrieved across sessions.
​
--code-graph
flag
Index the current project and enable the code-graph MCP server (tokensave). The agent can query call chains, definitions, and impact analysis without reading whole files.
​
--1m
flag
Request the 1M context window for Claude Code (appends the [1m] model suffix). Only applies to entitled subscription accounts.
​
--tool-search
string
Control Claude Code’s on-demand tool loading (deferral). Accepts true, false, auto, or auto:N (0–100). Defaults to true (keep deferral on) to prevent MCP/system tool schemas from inflating the context window.
​
--prepare-only
flag
Run setup steps (proxy start, MCP registration, tool install) without launching the agent binary. Useful for pre-warming in CI or container entrypoints.
​
--no-proxy
flag
Skip starting a new proxy process — connect to one already running on --port.
​
--learn
flag
Enable live traffic learning in the proxy (forwards --learn to headroom proxy).

​
Claude-specific flags

​
--no-tokensave
flag
Skip registration of the tokensave code-graph MCP compressor.
​
--serena
flag
Force-register the Serena MCP compressor even though tokensave is now the primary. Use when tokensave is unavailable on your platform.
​
--no-serena
flag
Never register the Serena backup compressor.
# Claude with 1M context
headroom wrap claude --1m

# Claude with specific model (passed through to claude binary)
headroom wrap claude -- --model claude-opus-4-5

# Claude with memory and traffic learning
headroom wrap claude --memory --learn

# Claude with code graph intelligence
headroom wrap claude --code-graph

# Pass extra arguments to claude after --
headroom wrap claude -- --dangerously-skip-permissions

​
Copilot-specific flags

​
--subscription
flag
Use GitHub Copilot’s subscription (hosted) API rather than a BYOK provider. Triggers the OAuth device-code flow if no saved token exists.
​
--provider-type
auto | anthropic | openai
default:"auto"
Copilot BYOK provider mode. auto selects anthropic for the default backend and openai for translated backends.
​
--wire-api
completions | responses
OpenAI-compatible Copilot wire API. Defaults to completions when --provider-type resolves to openai.
​
--backend
string
Force a specific BYOK backend: anthropic, anyllm, or litellm-<provider>.
To pass a model to the underlying agent (Claude Code or Copilot CLI), append it after --: headroom wrap claude -- --model claude-opus-4-5 or headroom wrap copilot -- --model gpt-4o.
# GitHub Copilot with subscription authentication
headroom wrap copilot --subscription

# GitHub Enterprise Server
headroom wrap copilot --subscription --domain my-ghe.example.com

# BYOK with Anthropic key
headroom wrap copilot

​
headroom unwrap

headroom unwrap <tool> removes Headroom’s configuration from the agent and optionally stops the proxy. 
headroom unwrap claude    # Remove routing config + stop proxy
headroom unwrap copilot   # Remove Copilot routing + stop proxy
headroom unwrap codex     # Restore codex config.toml + stop proxy
headroom unwrap opencode  # Restore opencode config + stop proxy
headroom unwrap openclaw  # Remove OpenClaw plugin
Tools with durable unwrap support (claude, copilot, codex, opencode, openclaw) restore the agent to its exact pre-wrap state using a snapshot taken at wrap time.

​
Unwrap flags (claude)

​
--port / -p
integer
default:"8787"
Port of the proxy to stop.
​
--no-stop-proxy
flag
Keep the proxy running after unwrapping.
​
--keep-mcp
flag
Leave Headroom MCP registrations in place.
​
--keep-rtk
flag
Leave rtk Claude hooks in place.

​
HEADROOM_CONTEXT_TOOL

Set this environment variable to choose between the two context tools:
ValueDescription
rtk (default)Rust Token Killer — prefix shell commands to filter/shrink their output (60–99 % savings)
lean-ctxLean-ctx — alternative context optimizer
# Use lean-ctx instead of rtk
HEADROOM_CONTEXT_TOOL=lean-ctx headroom wrap claude

​
How wrap works

  1. Starts headroom proxy as a background process on the requested port (unless --no-proxy)
  2. Waits for the proxy to become healthy (timeout: 45 s by default, 90 s when ML extras are detected)
  3. Installs the rtk (or lean-ctx) context tool and registers hooks
  4. Registers the headroom MCP server with the agent for CCR retrieval
  5. Optionally registers the tokensave code-graph MCP
  6. Sets environment variables (ANTHROPIC_BASE_URL, etc.) to route traffic through the proxy
  7. Launches the agent binary (for launch-type tools) or prints setup instructions
When the agent exits, the cleanup handler stops the proxy and restores any configuration files that were modified.
The proxy logs are written to ~/.headroom/logs/proxy-stdio.log and ~/.headroom/logs/proxy.log. If wrap fails to start, check those files for startup errors.

Build docs developers (and LLMs) love

Get started for freeTalk to us