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

The headroom wrap claude command launches a local proxy on port 8787, sets ANTHROPIC_BASE_URL to intercept API calls, and runs the Claude Code binary with optional memory sync and tool management features.

The headroom wrap command in the chopratejas/headroom repository provides a seamless way to intercept and manage Claude Code's API traffic through a local proxy. This functionality allows developers to inject custom middleware, manage context tokens, and synchronize persistent memory between Headroom and Claude Code's internal state. Learning how to use the headroom wrap command for Claude Code unlocks advanced debugging capabilities and enhanced context management for AI-assisted development workflows.

What Does Headroom Wrap Do?

When you execute headroom wrap claude, the tool performs API interception by creating a local HTTP proxy that sits between Claude Code and Anthropic's servers. According to the implementation in headroom/cli/wrap.py (lines 75-84), the command automatically sets the ANTHROPIC_BASE_URL environment variable to point at this proxy, ensuring all API requests route through Headroom's middleware layer.

This architecture enables several advanced features:

• Request/response logging for debugging API interactions
• Token management via RTK (Rust Token Killer) or lean-ctx integration
• Persistent memory synchronization between Headroom's SQLite store and Claude Code's ~/.claude folder
• MCP tool registration for extended functionality

Basic Usage Syntax

The fundamental command structure follows this pattern:

headroom wrap claude [OPTIONS] [-- <CLAUDE_ARGS>]

The -- separator distinguishes Headroom-specific options from arguments intended for the Claude Code binary itself. Anything after -- is forwarded verbatim to the claude executable.

Command-Line Options and Flags

The headroom wrap claude subcommand accepts several configuration flags defined in headroom/cli/wrap.py (lines 50-70).

Port Configuration (--port)

Override the default proxy port (8787):

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.

Persistent Memory (--memory)

Enable synchronization between Headroom's memory database and Claude Code's local storage:

headroom wrap claude --memory

When activated, Headroom syncs its SQLite memory store with the ~/.claude folder before the proxy starts.

Tool Search Control (--tool-search)

Control Claude Code's on-demand tool loading behavior:

headroom wrap claude --tool-search auto:50

Available modes include true (default), false, auto, and auto:N where N specifies a custom threshold.

Context Tool Management (--no-context-tool)

Skip the automatic installation of the context tool (RTK or lean-ctx):

headroom wrap claude --no-context-tool

By default, the CLI checks the HEADROOM_CONTEXT_TOOL environment variable (defaulting to rtk) and ensures the appropriate tool is installed via the _selected_context_tool() helper.

MCP Registration Flags (--no-mcp, --no-serena)

Disable specific MCP (Model Context Protocol) registrations:

headroom wrap claude --no-mcp --no-serena

The --no-mcp flag prevents registration of the MCP "retrieve tool," while --no-serena skips the optional Serena MCP registration.

Code Graph Integration (--code-graph)

Enable the live code-graph watcher:

headroom wrap claude --code-graph

This feature requires the headroom memory backend to be active and monitors your codebase for structural changes in real-time.

Passing Arguments to Claude Code (--)

Forward specific arguments to the Claude Code binary:

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

All arguments following -- are passed directly to the claude executable without modification.

Internal Workflow and Architecture

Understanding the execution flow helps troubleshoot issues when running the headroom wrap command for Claude Code:

1. Context Tool Verification: The CLI calls _selected_context_tool() to determine whether to use RTK or lean-ctx, then verifies installation via headroom/rtk/installer.py or headroom/lean_ctx/installer.py.

2. Memory Pre-Sync: If --memory is specified, Headroom synchronizes its persistent storage with Claude Code's local data before launching.

3. Proxy Initialization: The _start_proxy() function spawns the proxy as a background subprocess, configured via headroom/providers/claude.py which provides the proxy_base_url used to construct ANTHROPIC_BASE_URL.

4. Health Check: The CLI waits up to 45 seconds for the proxy to become reachable on the specified port.

5. Claude Execution: Finally, the claude binary executes with the modified environment variables and any forwarded arguments.

Practical Code Examples

Launch Claude Code with Default Settings

headroom wrap claude

This starts the proxy on port 8787 and runs claude with ANTHROPIC_BASE_URL=http://127.0.0.1:8787.

Use a Specific Model with Custom Port

headroom wrap claude --port 8888 -- --model claude-3-5-sonnet-20241022

Enable Full Feature Set

headroom wrap claude \
    --memory \
    --tool-search auto:50 \
    --code-graph \
    -- --model claude-sonnet-4-20250514

Minimal Proxy Mode (No Context Tools)

headroom wrap claude --no-context-tool --no-mcp

Useful when you need pure API interception without additional token management hooks.

Summary

• The headroom wrap claude command creates a local proxy on port 8787 by default, intercepting API calls via the ANTHROPIC_BASE_URL environment variable.
• Configuration options include memory syncing (--memory), tool search control (--tool-search), and MCP registration toggles (--no-mcp, --no-serena).
• The workflow automatically installs context tools (RTK or lean-ctx) unless disabled with --no-context-tool, handling the logic through _selected_context_tool() in headroom/cli/wrap.py.
• Arguments following -- pass directly to the Claude Code binary, allowing model selection and session resumption.
• The proxy waits up to 45 seconds to initialize before launching Claude Code.

Frequently Asked Questions

What is the default port for the headroom wrap proxy?

The default port is 8787. You can override this using the --port flag. If that port is occupied, the CLI detects the conflict and suggests the next available port.

How do I pass custom arguments to Claude Code when using headroom wrap?

Place arguments after the -- separator. For example: headroom wrap claude -- --model claude-sonnet-4-20250514 --resume. Everything following -- forwards directly to the claude binary.

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

RTK (Rust Token Killer) and lean-ctx are alternative implementations for managing context tokens in Claude Code. The tool checks the HEADROOM_CONTEXT_TOOL environment variable (defaulting to rtk) via the _selected_context_tool() function to determine which to install and use.

Why does headroom wrap fail to start if a proxy is already running?

The CLI prevents port collisions by checking for existing listeners before spawning the proxy subprocess. If the default or specified port is in use, the command exits with an error suggesting you use --port to select a different port or terminate the existing process.

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