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

> Learn to use the headroom wrap claude command to launch a local proxy for Claude Code. Intercept API calls, manage tools, and sync memory effortlessly.

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

---

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

```bash
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`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/wrap.py) (lines 50-70).

### Port Configuration (`--port`)

Override the default proxy port (8787):

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

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

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

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

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

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

```bash
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`](https://github.com/chopratejas/headroom/blob/main/headroom/rtk/installer.py) or [`headroom/lean_ctx/installer.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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

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

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

```

### Enable Full Feature Set

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

```

### Minimal Proxy Mode (No Context Tools)

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