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

> Master the headroom wrap command with Claude Code. Learn how to intercept API calls and run the claude binary locally. Get the complete guide now.

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

---

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

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

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

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

### Enabling Persistent Memory (`--memory`)

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

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

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

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

```

## Advanced Workflows

### Passing Arguments to Claude Code

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

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

```

```bash
headroom wrap claude -- --resume

```

### Complete Configuration Example

Combine multiple Headroom features with specific Claude Code settings:

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