How to Use the Headroom Wrap Command with Claude Code: Complete Guide

The headroom wrap claude command launches a Headroom proxy on port 8787, intercepts Claude Code's API calls through that proxy, and executes the claude binary with the ANTHROPIC_BASE_URL environment variable pointing to the local proxy.

The headroom wrap command enables seamless integration between the Headroom proxy infrastructure and Claude Code, allowing you to manage API traffic while maintaining full compatibility with Anthropic's CLI tool. This implementation in the chopratejas/headroom repository supports advanced features like persistent memory synchronization, controlled tool loading, and token optimization via Rust Token Killer (RTK) or lean-ctx utilities.

Understanding the Architecture

When you execute headroom wrap claude, the CLI performs several operations defined in headroom/cli/wrap.py. First, it calls _selected_context_tool() to ensure either RTK (Rust Token Killer) or lean-ctx is installed based on the HEADROOM_CONTEXT_TOOL environment variable (defaulting to rtk). If you specify --memory, Headroom synchronizes its SQLite memory store with Claude Code's ~/.claude folder before starting the proxy. The system then spawns a background proxy subprocess via _start_proxy and waits up to 45 seconds for it to become reachable on the specified port. Finally, it launches the claude binary with ANTHROPIC_BASE_URL set to the proxy URL provided by headroom/providers/claude.py.

Basic Usage

Starting the Proxy and Claude Code

The simplest invocation starts the proxy on the default port and launches Claude Code:

headroom wrap claude

This sets ANTHROPIC_BASE_URL=http://127.0.0.1:8787 and executes the claude binary found on your system's PATH.

Command Structure

The claude sub-command accepts specific Headroom flags followed by a -- separator for any arguments intended for Claude Code itself:

headroom wrap claude [headroom-options] -- [claude-options]

Configuration Options

Customizing the Proxy Port (--port)

Override the default port 8787 to avoid conflicts or run multiple instances:

headroom wrap claude --port 9999

If a proxy is already running on the specified port, the CLI reports an error and suggests the next available port.

Enabling Persistent Memory (--memory)

Synchronize Headroom's memory database with Claude Code's local storage:

headroom wrap claude --memory

This requires the headroom memory back-end and ensures context persistence across sessions by syncing with the ~/.claude directory before the proxy starts.

Controlling Tool Search (--tool-search)

Manage Claude Code's on-demand tool loading behavior with specific modes:

• true (default): Enable automatic tool searching
• false: Disable automatic tool loading
• auto: Use automatic mode with default thresholds
• auto:N: Use automatic mode with custom threshold N

headroom wrap claude --tool-search auto:50

Disabling Optional Components

Skip specific integrations when you don't need them:

• --no-context-tool: Skip installation of RTK or lean-ctx (disable token-killing hooks)
• --no-mcp: Do not register the MCP "retrieve tool"
• --no-serena: Skip the optional Serena MCP registration
• --code-graph: Enable the live code-graph watcher (requires headroom memory back-end)

headroom wrap claude --no-context-tool --code-graph

Advanced Workflows

Passing Arguments to Claude Code

Forward any Claude Code-specific arguments after the -- separator:

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

headroom wrap claude -- --resume

Complete Configuration Example

Combine multiple Headroom features with specific Claude Code settings:

headroom wrap claude \
    --memory \
    --tool-search auto:50 \
    --code-graph \
    --port 8888 \
    -- --model claude-3-5-sonnet-20241022

This configuration runs Claude Code with persistent memory, moderated tool-search mode, live code-graph watching, and a custom proxy port, while specifying a particular model version.

Summary

• headroom wrap claude creates a proxy on port 8787 and launches Claude Code with API calls routed through Headroom.
• The command installs context tools (RTK or lean-ctx) automatically based on the HEADROOM_CONTEXT_TOOL environment variable.
• Use --memory to synchronize Headroom's SQLite store with Claude Code's ~/.claude folder before starting.
• Pass arguments to Claude Code after the -- separator.
• All proxy initialization logic, including the 45-second health check and environment setup, is implemented in headroom/cli/wrap.py.

Frequently Asked Questions

What does the headroom wrap command do with Claude Code?

The headroom wrap claude command establishes a local proxy that intercepts all API calls between Claude Code and Anthropic's servers. It sets the ANTHROPIC_BASE_URL environment variable to point at this proxy, allowing Headroom to log, modify, or extend API functionality while maintaining transparent communication with Claude Code's binary.

How do I change the default port when wrapping Claude Code?

Use the --port flag followed by your desired port number. For example, headroom wrap claude --port 9999 starts the proxy on port 9999 instead of the default 8787. If the port is already occupied, the CLI will notify you and suggest an alternative.

What is the difference between RTK and lean-ctx context tools?

RTK (Rust Token Killer) and lean-ctx are alternative context management tools that Headroom can install to help Claude Code optimize token usage. The _selected_context_tool() function in the source code checks the HEADROOM_CONTEXT_TOOL environment variable (defaulting to rtk) to determine which tool to install. You can skip installation entirely with --no-context-tool.

Can I use headroom wrap with existing Claude Code sessions?

Yes, by passing the --resume flag after the -- separator: headroom wrap claude -- --resume. This forwards the resume command directly to the Claude Code binary, allowing you to continue previous conversations while still routing traffic through the Headroom proxy.

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