AI Context and Compression Management

https://headroom-docs.vercel.app/docs
Admin
This project provides documentation for a system focused on managing and optimizing AI models,...
Tokens:174,538
Snippets:1,401
Trust Score:7.8
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install OpenClaw plugin with headroom wrap

Source: https://headroom-docs.vercel.app/docs/openclaw

Recommended one-command setup for the OpenClaw plugin. Run this to install and configure the plugin.

```text
headroom wrap openclaw
```

--------------------------------

### Install specific Headroom extras

Source: https://headroom-docs.vercel.app/docs/installation

Installs a combination of extras by listing them comma-separated inside the brackets. This example installs the proxy, langchain, and ml extras together.

```bash
pip install "headroom-ai[proxy,langchain,ml]"
```

--------------------------------

### Start the Headroom proxy

Source: https://headroom-docs.vercel.app/docs/anthropic-sdk

Install the proxy package and start the local Headroom proxy, which is required before using the SDK.

```bash
pip install "headroom-ai[proxy]"
headroom proxy
```

--------------------------------

### Set up Antigravity IDE with headroom wrap and mcp install

Source: https://headroom-docs.vercel.app/docs/proxy

Commands to start the proxy and print Antigravity setup instructions, and to register the Headroom MCP server in Antigravity. The wrap command prints a custom OpenAI-compatible base URL for model-provider settings.

```bash
headroom wrap antigravity          # Start proxy + print Antigravity setup instructions
headroom mcp install --agent antigravity   # Register the Headroom MCP server in Antigravity
```

--------------------------------

### Dockerfile to install Headroom with build tools in one layer

Source: https://headroom-docs.vercel.app/docs/troubleshooting

Dockerfile example that installs build tools, installs headroom-ai[proxy], then removes build tools to keep the image clean.

```dockerfile
FROM python:3.11-slim
RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
    && pip install "headroom-ai[proxy]" \
    && apt-get purge -y build-essential && apt-get autoremove -y \
    && rm -rf /var/lib/apt/lists/*
```

--------------------------------

### Quick Start: Using SharedContext

Source: https://headroom-docs.vercel.app/docs/shared-context

Shows how to create a SharedContext, store large output with put(), retrieve a compressed version with get(), and get the full version with { full: true }.

```TypeScript
import { SharedContext } from "headroom-ai";

const ctx = new SharedContext();

// Agent A stores large output
const entry = await ctx.put("research", bigResearchOutput, {
  agent: "researcher",
});

// Agent B gets compressed version (~80% smaller)
const summary = ctx.get("research");

// Agent B needs full details on demand
const full = ctx.get("research", { full: true });
```

--------------------------------

### Install Headroom proxy extras and run with remote access

Source: https://headroom-docs.vercel.app/docs/litellm

Install the proxy extras and start the Headroom proxy with remote access enabled. Without HEADROOM_COMPRESS_ALLOW_REMOTE=1, remote callers receive 404, not 403. If HEADROOM_PROXY_TOKEN is set, send it as X-Headroom-Proxy-Token or get 401.

```bash
pip install "headroom-ai[proxy]"

# Headroom is loopback-only by default and answers remote callers with 404.
HEADROOM_COMPRESS_ALLOW_REMOTE=1 headroom proxy
```

--------------------------------

### Install proxy extras and start Headroom proxy

Source: https://headroom-docs.vercel.app/docs/installation

Installs the proxy extras for the TypeScript SDK and starts the Headroom proxy on port 8787. The proxy runs the full compression pipeline in Python and must be running before using the SDK.

```bash
pip install "headroom-ai[proxy]"
headroom proxy --port 8787
```

--------------------------------

### Install headroom-ai and litellm

Source: https://headroom-docs.vercel.app/docs/litellm

Install the required packages using pip.

```bash
pip install headroom-ai litellm
```

--------------------------------

### Install Headroom optional dependencies

Source: https://headroom-docs.vercel.app/docs/troubleshooting

Commands to install optional extras: proxy, relevance, code, and all.

```bash
# For proxy server
pip install "headroom-ai[proxy]"

# For embedding-based relevance scoring
pip install "headroom-ai[relevance]"

# For code compression (tree-sitter)
pip install "headroom-ai[code]"

# For everything
pip install "headroom-ai[all]"
```

--------------------------------

### Install act and actionlint

Source: https://headroom-docs.vercel.app/docs/releases

Installation commands for act and actionlint on macOS and Windows.

```bash
# macOS
brew install act actionlint

# Windows
winget install act
winget install actionlint

```

--------------------------------

### OpenAIProvider usage example

Source: https://headroom-docs.vercel.app/docs/api-reference

Shows how to instantiate OpenAIProvider, get a token counter for a model, count text, get the context limit, and estimate cost. The context limit for gpt-4o is 128000.

```python
from headroom import OpenAIProvider

provider = OpenAIProvider()

counter = provider.get_token_counter("gpt-4o")
tokens = counter.count_text("Hello, world!")
limit = provider.get_context_limit("gpt-4o")  # 128000
cost = provider.estimate_cost(input_tokens=1000, output_tokens=500, model="gpt-4o")
```

--------------------------------

### Install Headroom with proxy and otel extras

Source: https://headroom-docs.vercel.app/docs/metrics

Install the headroom-ai package with the 'proxy' and 'otel' extras to enable OTLP metric export.

```bash
pip install "headroom-ai[proxy,otel]"
```

--------------------------------

### Install all Headroom extras

Source: https://headroom-docs.vercel.app/docs/installation

Installs the full built-in runtime bundle with the [all] extra. This includes proxy, code, ml, memory, relevance, image, reports, otel, evals, voice, html, mcp, and spreadsheet. Not every integration or optional backend is included.

```bash
pip install "headroom-ai[all]"
```

--------------------------------

### Install and enable headroom-oauth2 with pip and headroom proxy

Source: https://headroom-docs.vercel.app/docs/oauth2-upstream

Install the extension via pip and start the proxy with the oauth2 extension enabled. The proxy command uses the litellm-openai backend and the --proxy-extension oauth2 flag.

```bash
pip install headroom-oauth2
headroom proxy --backend litellm-openai --proxy-extension oauth2
```

--------------------------------

### Install Headroom MCP SDK

Source: https://headroom-docs.vercel.app/docs/mcp

Run this command to install the Headroom MCP SDK when the error 'MCP SDK not installed' appears.

```bash
pip install "headroom-ai[mcp]"
```

--------------------------------

### Install Headroom with uv tool or pip (source build prerequisites)

Source: https://headroom-docs.vercel.app/docs/installation

Commands to install Headroom with all extras after installing the MSVC toolchain and Rust. Use a fresh PowerShell so PATH updates take effect.

```bash
uv tool install --python 3.13 "headroom-ai[all]"
# or
pip install "headroom-ai[all]"
```

--------------------------------

### GoogleProvider instantiation example

Source: https://headroom-docs.vercel.app/docs/api-reference

Shows how to instantiate GoogleProvider from the headroom.providers module.

```python
from headroom.providers import GoogleProvider

provider = GoogleProvider()
```

--------------------------------

### Install and run Headroom proxy with gunicorn

Source: https://headroom-docs.vercel.app/docs/proxy

Install gunicorn and start the Headroom proxy with 4 workers on port 8787. The import string calls the create_app factory because headroom.proxy.server has no module-level app object. Callers must send Authorization: Bearer replace-with-a-secret or X-Headroom-Proxy-Token: replace-with-a-secret.

```bash
pip install gunicorn

gunicorn "headroom.proxy.server:create_app()" \
  --workers 4 \
  --bind 0.0.0.0:8787 \
  --worker-class uvicorn.workers.UvicornWorker
# Callers must send `Authorization: Bearer replace-with-a-secret` or
# `X-Headroom-Proxy-Token: replace-with-a-secret`.
```

--------------------------------

### Start Headroom proxy for TypeScript SDK

Source: https://headroom-docs.vercel.app/docs/quickstart

The TypeScript SDK requires a local proxy. Install the proxy with uv or pip, then run it on port 8787.

```bash
uv tool install --python 3.13 "headroom-ai[proxy]"
# or, inside a Python project: pip install "headroom-ai[proxy]"
headroom proxy --port 8787
```

--------------------------------

### Start OpenCode

Source: https://headroom-docs.vercel.app/docs/opencode-deepseek

Run the 'opencode' command to start OpenCode. Then use /models to confirm both DeepSeek models appear under 'Headroom Proxy' and select one with /model deepseek-flash or /model deepseek-v4-pro.

```bash
opencode
```

--------------------------------

### Headroom install commands

Source: https://headroom-docs.vercel.app/docs/persistent-installs

List of commands for managing persistent installs: apply, status, start, stop, restart, remove. The apply command creates or updates a named deployment profile, stores its manifest under ~/.headroom/deploy/<profile>/manifest.json, applies reversible configuration changes, and starts the selected runtime. The status command distinguishes the default backend from Anthropic and OpenAI protocol targets.

```bash
headroom install apply
headroom install status
headroom install start
headroom install stop
headroom install restart
headroom install remove
```

--------------------------------

### Manual install of OpenClaw plugin

Source: https://headroom-docs.vercel.app/docs/openclaw

Manual installation steps: install the headroom-ai package with proxy extras, then install the OpenClaw plugin with the unsafe flag. The --dangerously-force-unsafe-install flag is required because OpenClaw treats process-launching plugins as unsafe by default.

```text
pip install "headroom-ai[proxy]"
openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw
```

--------------------------------

### Install headroom-ai with pnpm and yarn

Source: https://headroom-docs.vercel.app/docs/installation

Alternative package manager commands to install 'headroom-ai'.

```bash
pnpm add headroom-ai
yarn add headroom-ai
```

--------------------------------

### Set up local secrets

Source: https://headroom-docs.vercel.app/docs/releases

Copies the example environment file and instructs to edit it with test tokens.

```bash
cp .env.act.example .env.act
# Edit .env.act and add your test tokens

```

--------------------------------

### Install Headroom with Agno support

Source: https://headroom-docs.vercel.app/docs/agno

Installs the headroom-ai package with the agno extra along with the agno package.

```bash
pip install "headroom-ai[agno]" agno
```

--------------------------------

### Install onnxruntime or set ORT_DYLIB_PATH manually

Source: https://headroom-docs.vercel.app/docs/troubleshooting

If the pin is skipped (library install without onnxruntime), install it or point the variable at any modern ONNX Runtime yourself.

```bash
pip install onnxruntime
# or
$env:ORT_DYLIB_PATH = "C:\path\to\onnxruntime.dll"
```

--------------------------------

### Example output for savings check

Source: https://headroom-docs.vercel.app/docs/quickstart

Example console output showing token counts, compression percentage, and applied transforms.

```Text
Tokens before: 45000
Tokens after:  4500
Tokens saved:  40500
Compression:   90%
Transforms:    smart_crusher, cache_aligner
```

--------------------------------

### Quick Start: Launch Grok

Source: https://headroom-docs.vercel.app/docs/grok-build

Run this in another terminal from the same project directory after wrapping Grok Build.

```bash
grok
```

--------------------------------

### Quick Start: Wrap Grok Build

Source: https://headroom-docs.vercel.app/docs/grok-build

Run this command to start or reuse the Headroom proxy and inject the model override into Grok's config.toml. It prints next steps for launching `grok`.

```bash
headroom wrap grok-build
```

--------------------------------

### Check port usage and start proxy with debug logging

Source: https://headroom-docs.vercel.app/docs/troubleshooting

Use these commands when 'headroom proxy' fails or hangs. Check if port 8787 is in use, try a different port, install missing dependencies, and run with debug logging to diagnose the issue.

```bash
# Check if port is already in use
lsof -i :8787

# Try a different port
headroom proxy --port 8788

# Check for missing dependencies
pip install "headroom-ai[proxy]"

# Run with debug logging
headroom proxy --log-file ~/.headroom/logs/proxy.jsonl --log-messages
```

--------------------------------

### Proxy start vs reuse with --openai-api-url

Source: https://headroom-docs.vercel.app/docs/opencode

Shows two ways to use --openai-api-url: let wrap start the proxy pointing at DeepSeek, or reuse a proxy you started yourself with --no-proxy. With --no-proxy, wrap checks the listener on --port and exits with an error before rewriting opencode.json if it is not a Headroom proxy or targets a different upstream.

```bash
# wrap starts the proxy and points it at DeepSeek
headroom wrap opencode --openai-api-url https://api.deepseek.com/v1

# reuse a proxy you started yourself — it must already target that upstream
headroom proxy --port 8787 --openai-api-url https://api.deepseek.com/v1
headroom wrap opencode --no-proxy --openai-api-url https://api.deepseek.com/v1
```

--------------------------------

### Install Headroom and wrap Claude Code

Source: https://headroom-docs.vercel.app/docs/claude-code-azure-foundry

Run these commands to install the Headroom proxy and wrap Claude Code. Requires the environment variable CLAUDE_CODE_USE_FOUNDRY=1 to be set. The wrap command automatically derives the Azure endpoint from ANTHROPIC_FOUNDRY_RESOURCE, starts the proxy, and points Claude Code to it.

```bash
pip install "headroom-ai[proxy]"
headroom wrap claude
```

--------------------------------

### Install Vertex SDK with Headroom proxy extra

Source: https://headroom-docs.vercel.app/docs/proxy

Install the google-cloud-aiplatform SDK alongside Headroom's proxy extra. Required for the Vertex AI backend; without it, requests fail with litellm.BadRequestError mentioning 'No module named vertexai'.

```bash
pip install "headroom-ai[proxy]" "google-cloud-aiplatform>=1.38"
```

--------------------------------

### Linux one-line install

Source: https://headroom-docs.vercel.app/docs/docker-install

Installs Headroom via Docker on Linux using curl and bash. Requires Docker to be installed and available.

```bash
curl -fsSL https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.sh | bash
```

--------------------------------

### Install Headroom with proxy extras

Source: https://headroom-docs.vercel.app/docs/local-llm-prefill

Install the headroom-ai package with the proxy extra using pip.

```text
pip install "headroom-ai[proxy]"
```

--------------------------------

### Start Headroom proxy with basic usage, public access, and logging/budget

Source: https://headroom-docs.vercel.app/docs/proxy

Commands to start the Headroom proxy. Basic usage runs 'headroom proxy'. For public access, set HEADROOM_PROXY_TOKEN and use --host 0.0.0.0 --port 8080; callers must send Authorization: Bearer or X-Headroom-Proxy-Token. The third command adds logging to a file and sets a budget.

```bash
# Basic usage
headroom proxy

# Deliberate public access, with the existing token protocol
HEADROOM_PROXY_TOKEN='replace-with-a-secret' headroom proxy --host 0.0.0.0 --port 8080
# Send `Authorization: Bearer replace-with-a-secret` or
# `X-Headroom-Proxy-Token: replace-with-a-secret` from the caller.

# With logging and budget
headroom proxy \
  --log-file /var/log/headroom.jsonl \
  --budget 100.0
```

--------------------------------

### TypeScript SDK: Install headroom-ai

Source: https://headroom-docs.vercel.app/docs

Install the TypeScript SDK package headroom-ai.

```bash
npm install headroom-ai
```

--------------------------------

### Install Headroom MCP tools and proxy via pip

Source: https://headroom-docs.vercel.app/docs/mcp

Install the lightweight MCP tools with 'headroom-ai[mcp]' or include the proxy with 'headroom-ai[proxy]'.

```bash
# MCP tools only (lightweight)
pip install "headroom-ai[mcp]"

# Or with the proxy
pip install "headroom-ai[proxy]"
```

--------------------------------

### Start proxy with output shaping

Source: https://headroom-docs.vercel.app/docs/opencode-deepseek

Starts the proxy with output shaping enabled (HEADROOM_OUTPUT_SHAPER=1) and verbosity level 2, which skips preambles/postambles and doesn't restate code/file content already in context. This reduces token usage and cost.

```bash
HEADROOM_OUTPUT_SHAPER=1 HEADROOM_VERBOSITY_LEVEL=2 \
headroom proxy --port 8787 --openai-api-url https://api.deepseek.com/v1
```

--------------------------------

### Install headroom-ai and autogen-agentchat

Source: https://headroom-docs.vercel.app/docs/autogen

Install the required packages for using Headroom with AutoGen.

```bash
pip install headroom-ai autogen-agentchat
```

--------------------------------

### headroomMiddleware() with options

Source: https://headroom-docs.vercel.app/docs/vercel-ai-sdk

Pass options to control compression behavior. This example sets the model and baseUrl for the proxy.

```typescript
import { headroomMiddleware } from 'headroom-ai/vercel-ai';

const middleware = headroomMiddleware({
  model: 'gpt-4o',
  baseUrl: 'http://localhost:8787',
});
```

--------------------------------

### Example logging output

Source: https://headroom-docs.vercel.app/docs/metrics

Example output from the logging configuration, showing INFO and DEBUG messages from the pipeline and smart crusher.

```text
INFO:headroom.transforms.pipeline:Pipeline complete: 45000 -> 4500 tokens (saved 40500, 90.0% reduction)
INFO:headroom.transforms.smart_crusher:SmartCrusher applied top_n strategy: kept 15 of 1000 items
DEBUG:headroom.transforms.smart_crusher:Kept items: [0,1,2,42,77,97,98,99] (errors at 42, warnings at 77)
```

--------------------------------

### Install headroom-ai and openai packages

Source: https://headroom-docs.vercel.app/docs/openai-sdk

Install the required npm packages for using the Headroom OpenAI SDK wrapper.

```bash
npm install headroom-ai openai
```

--------------------------------

### Install headroom-ai and crewai

Source: https://headroom-docs.vercel.app/docs/crewai

Install the required packages for the CrewAI integration.

```bash
pip install headroom-ai crewai
```

--------------------------------

### Install headroom-ai and Anthropic SDK

Source: https://headroom-docs.vercel.app/docs/anthropic-sdk

Install the required npm packages for the Headroom Anthropic SDK wrapper.

```bash
npm install headroom-ai @anthropic-ai/sdk
```

--------------------------------

### Install Headroom and Strands Agents

Source: https://headroom-docs.vercel.app/docs/strands

Install the required packages for using Headroom with Strands Agents.

```bash
pip install headroom-ai strands-agents
```

--------------------------------

### Persistent service on local machine with headroom install apply

Source: https://headroom-docs.vercel.app/docs/persistent-installs

Installs a background service on the current machine, applies persistent tool wiring, and keeps the proxy healthy on port 8787.

```bash
headroom install apply --preset persistent-service --providers auto
headroom install status
```

--------------------------------

### MCP Tools: Install and Launch Claude

Source: https://headroom-docs.vercel.app/docs

Install MCP tools (headroom_compress, headroom_retrieve, headroom_stats) and launch Claude.

```bash
headroom mcp install && claude
```

--------------------------------

### Add uv tool binaries to PATH

Source: https://headroom-docs.vercel.app/docs/opencode-deepseek

Add ~/.local/bin to your PATH so the headroom command is found after installation via uv tool install.

```bash
export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Install headroom-ai with code extra

Source: https://headroom-docs.vercel.app/docs/code-compression

Installs the headroom-ai package with the code extra to enable tree-sitter language pack.

```bash
# Install tree-sitter language pack
pip install "headroom-ai[code]"
```

--------------------------------

### Install Headroom LangChain and LangGraph packages

Source: https://headroom-docs.vercel.app/docs/langchain

Install the headroom-ai package with the langchain extra for langchain-core and langchain-openai, or the langgraph extra which also includes langgraph.

```bash
pip install "headroom-ai[langchain]"    # langchain-core + langchain-openai
pip install "headroom-ai[langgraph]"    # the above, plus langgraph
```

--------------------------------

### Run proxy with Compose (macOS/Linux)

Source: https://headroom-docs.vercel.app/docs/docker-install

Starts the `proxy` service in the foreground using `docker/docker-compose.native.yml` on macOS/Linux. Requires `HEADROOM_HOST_HOME` and `HEADROOM_WORKSPACE` to be set.

```bash
export HEADROOM_HOST_HOME="$HOME"
export HEADROOM_WORKSPACE="$PWD"
docker compose -f docker/docker-compose.native.yml up proxy
```

--------------------------------

### Verify headroom-ai install with Node

Source: https://headroom-docs.vercel.app/docs/installation

Runs a one-liner to confirm the 'headroom-ai' package loads correctly.

```bash
node -e "const h = require('headroom-ai'); console.log('headroom-ai loaded')"
```

--------------------------------

### Start Headroom Proxy

Source: https://headroom-docs.vercel.app/docs/mcp

Start the proxy server in another terminal. Only needed for proxy-backed retrieval.

```bash
headroom proxy
```

--------------------------------

### Validate configuration at startup

Source: https://headroom-docs.vercel.app/docs/configuration

Calls validate_setup() and prints configuration issues for provider, storage, config, and cache_optimizer checks.

```python
result = client.validate_setup()

if not result["valid"]:
    print("Configuration issues:")
    for check in ("provider", "storage", "config", "cache_optimizer"):
        if result[check]["error"]:
            print(f"  - {check}: {result[check]['error']}")
```

--------------------------------

### Undo with custom settings file

Source: https://headroom-docs.vercel.app/docs/vscode-claude-code

Use this command if you used --settings-file during setup. Pass the same option when undoing it to restore the correct settings file.

```text
headroom unwrap vscode-claude --settings-file /path/to/.claude/settings.json
```

--------------------------------

### Install npm packages for Vercel AI SDK integration

Source: https://headroom-docs.vercel.app/docs/vercel-ai-sdk

Install the required npm packages: headroom-ai, ai, and @ai-sdk/openai. This is the first step before using any integration pattern.

```bash
npm install headroom-ai ai @ai-sdk/openai
```

--------------------------------

### Verify Headroom installation by printing version

Source: https://headroom-docs.vercel.app/docs/installation

Runs a Python one-liner to import headroom and print its version, confirming the installation succeeded.

```python
python -c "import headroom; print(headroom.__version__)"
```

--------------------------------

### headroom install apply provider selection commands

Source: https://headroom-docs.vercel.app/docs/persistent-installs

Commands to configure persistent installs with different provider scopes: auto-detect, all targets, or manual target selection. Use --providers manual with --target flags to configure only named tools.

```bash
headroom install apply --providers auto
headroom install apply --providers all --scope user
headroom install apply --providers manual --target claude --target copilot
```

--------------------------------

### Start Headroom proxy with optimization disabled

Source: https://headroom-docs.vercel.app/docs/local-llm-prefill

Start Headroom as a transparent proxy on port 8787, forwarding to the local server at http://127.0.0.1:8000, with optimization disabled using --no-optimize.

```text
headroom proxy \
  --port 8787 \
  --openai-api-url http://127.0.0.1:8000 \
  --no-optimize
```

--------------------------------

### ValidationError on Setup - Validate setup and common issues

Source: https://headroom-docs.vercel.app/docs/troubleshooting

Call validate_setup() to check the configuration. The output shows common issues such as missing API key, storage problems, and invalid mode, with suggested fixes.

```python
result = client.validate_setup()
print(result)

# Common issues:
# {"provider": {"ok": False, "error": "No API key"}}
#   -> Set OPENAI_API_KEY or pass api_key to OpenAI()
#
# {"storage": {"ok": False, "error": "unable to open database"}}
#   -> Check path permissions, use :memory: for testing
#
# {"config": {"ok": False, "error": "Invalid mode"}}
#   -> Use "audit" or "optimize" only
```

--------------------------------

### Start Headroom proxy and connect client

Source: https://headroom-docs.vercel.app/docs/image-compression

Starts the Headroom proxy on port 8787 and connects a client by setting ANTHROPIC_BASE_URL. Images are compressed automatically without code changes.

```bash
# Start the proxy
headroom proxy --port 8787

# Connect your client -- images are compressed automatically
ANTHROPIC_BASE_URL=http://localhost:8787 claude
```

--------------------------------

### Install Headroom with pipx using Python 3.13

Source: https://headroom-docs.vercel.app/docs/installation

Installs Headroom with all extras via pipx, explicitly using Python 3.13 to avoid resolving an older compatible release.

```bash
pipx install --python python3.13 "headroom-ai[all]"
```

--------------------------------

### Install Headroom core package with pip

Source: https://headroom-docs.vercel.app/docs/installation

Installs the core headroom-ai package from PyPI. Includes compress(), SmartCrusher, CacheAligner, and live-zone ContentRouter compression with no heavy dependencies.

```bash
pip install headroom-ai
```

--------------------------------

### Multi-Agent Shared Context Example

Source: https://headroom-docs.vercel.app/docs

Shows how to use the SharedContext API to store and retrieve data between agents. The example creates a context, puts a large output under a key, and retrieves it as a summary.

```python
ctx = SharedContext()
ctx.put("research", big_output)
summary = ctx.get("research")
```

--------------------------------

### Quick Start: Unwrap Grok Build

Source: https://headroom-docs.vercel.app/docs/grok-build

Run this when done to restore the pre-wrap config.toml from backup or strip Headroom marker blocks and in-place base_url rewrites.

```bash
headroom unwrap grok-build
```

--------------------------------

### headroom install with OpenCode provider scope

Source: https://headroom-docs.vercel.app/docs/opencode

Runs `headroom install` with `--scope provider` to write the Headroom provider into `~/.config/opencode/opencode.json` and keep the proxy running on port 8787. The default user scope only writes shell environment configuration, so `--scope provider` is required for OpenCode.

```bash
headroom install apply --preset persistent-service --scope provider --providers manual --target opencode
```

--------------------------------

### Persistent Docker with headroom install apply

Source: https://headroom-docs.vercel.app/docs/persistent-installs

Uses Docker's restart policy instead of an OS supervisor. Can be used directly from the Docker-native host wrapper for install, status, start, stop, restart, and remove operations.

```bash
headroom install apply --preset persistent-docker --scope user --providers auto
```

--------------------------------

### Python plugin config and workspace directory helpers

Source: https://headroom-docs.vercel.app/docs/filesystem-contract

Use these helpers to get per-plugin directories under the config and workspace roots. The returned paths are pathlib.Path objects; call mkdir() to create them. The example writes a settings.json file to the config directory.

```python
from headroom import paths

cfg_dir = paths.plugin_config_dir("my-plugin")
# → ~/.headroom/config/plugins/my-plugin

state_dir = paths.plugin_workspace_dir("my-plugin")
# → ~/.headroom/plugins/my-plugin

cfg_dir.mkdir(parents=True, exist_ok=True)
(cfg_dir / "settings.json").write_text("{}")
```

--------------------------------

### Headroom proxy CLI optional feature commands

Source: https://headroom-docs.vercel.app/docs/proxy

Example commands for enabling memory, learning, and debugging features, and using the HEADROOM_COMPRESS_PASSTHROUGH environment variable.

```bash
headroom proxy --memory
headroom proxy --learn --min-evidence 3
headroom proxy --codex-wire-debug
HEADROOM_COMPRESS_PASSTHROUGH=1 headroom proxy
```

--------------------------------

### Extend a profile with env overrides

Source: https://headroom-docs.vercel.app/docs/proxy

Shows how to start from a named profile and override individual settings using environment variables.

```bash
# Start from coding but force Kompress on
HEADROOM_SAVINGS_PROFILE=coding HEADROOM_FORCE_KOMPRESS=1 headroom proxy

# Start from balanced but lower the keep-ratio
HEADROOM_SAVINGS_PROFILE=balanced HEADROOM_TARGET_RATIO=0.15 headroom proxy
```

--------------------------------

### Run proxy with Compose (Windows PowerShell)

Source: https://headroom-docs.vercel.app/docs/docker-install

Starts the `proxy` service in the foreground using `docker/docker-compose.native.yml` on Windows PowerShell. Requires `HEADROOM_HOST_HOME` and `HEADROOM_WORKSPACE` to be set.

```powershell
$env:HEADROOM_HOST_HOME = $HOME
$env:HEADROOM_WORKSPACE = (Get-Location).Path
docker compose -f docker/docker-compose.native.yml up proxy
```

--------------------------------

### Start persistent Docker proxy with Compose (macOS/Linux)

Source: https://headroom-docs.vercel.app/docs/docker-install

Sets environment variables and starts the `proxy` service in detached mode using `docker/docker-compose.native.yml`. The `proxy` service uses `restart: unless-stopped` to act as an always-on runtime. `HEADROOM_WORKSPACE` is bind-mounted as `/workspace`.

```bash
export HEADROOM_HOST_HOME="$HOME"
export HEADROOM_WORKSPACE="$PWD"
docker compose -f docker/docker-compose.native.yml up -d proxy
```

--------------------------------

### Quick Start: Compress messages with SmartCrusher in TypeScript

Source: https://headroom-docs.vercel.app/docs/smart-crusher

Use the compress function from headroom-ai to automatically compress JSON tool outputs. The example shows a system message, user message, and a tool message with a large JSON result. The output logs the number of tokens saved and notes that SmartCrusher keeps errors, anomalies, and relevant items.

```TypeScript
import { compress } from "headroom-ai";

// SmartCrusher fires automatically for JSON tool outputs
const messages = [
  { role: "system" as const, content: "You are a helpful assistant." },
  { role: "user" as const, content: "Find errors in the last 24 hours" },
  {
    role: "tool" as const,
    content: JSON.stringify({ results: new Array(1000).fill({ status: "ok" }) }),
    tool_call_id: "call_1",
  },
];

const result = await compress(messages);
console.log(`Tokens saved: ${result.tokensSaved}`);
// SmartCrusher keeps errors, anomalies, and relevant items
```

--------------------------------

### Initialize memory with OpenAI-compatible clients

Source: https://headroom-docs.vercel.app/docs/memory

Shows how to wrap OpenAI, Azure OpenAI, and Groq clients with with_memory to enable memory functionality. Requires the openai and groq packages.

```python
from openai import OpenAI
from headroom import with_memory

# OpenAI
client = with_memory(OpenAI(), user_id="alice")

# Azure OpenAI
client = with_memory(
    OpenAI(base_url="https://your-resource.openai.azure.com/..."),
    user_id="alice",
)

# Groq
from groq import Groq
client = with_memory(Groq(), user_id="alice")
```

--------------------------------

### macOS (bash 4.3+) one-line install

Source: https://headroom-docs.vercel.app/docs/docker-install

Installs Headroom via Docker on macOS using a bash 4.3+ interpreter. Stock /bin/bash is 3.2, so install a newer bash (e.g., via Homebrew) and run the installer with that shell. The installed wrapper pins that same bash interpreter.

```bash
curl -fsSL https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.sh | "$(brew --prefix bash)/bin/bash"
```

--------------------------------

### validate_setup()

Source: https://headroom-docs.vercel.app/docs/api-reference

Validate that the client is configured correctly. Returns a dict with 'valid' and per-component status.

```APIDOC
## validate_setup()

### Description
Validate that the client is configured correctly. Returns a dict with 'valid' and per-component status.

### Returns
- **valid** (boolean) - Whether the setup is valid.
- **provider** (object) - Provider status with 'ok' or 'error'.
- **storage** (object) - Storage status with 'ok' or 'error'.
- **config** (object) - Config status with 'ok' or 'error'.
- **cache_optimizer** (object) - Cache optimizer status with 'ok' or 'error'.

### Example (Python)
```python
result = client.validate_setup()
# Returns {"valid": bool, "provider": {...}, "storage": {...},
#          "config": {...}, "cache_optimizer": {...}}, each with "ok"/"error"
if not result["valid"]:
    for key in ("provider", "storage", "config", "cache_optimizer"):
        if not result[key]["ok"]:
            print(f"  - {key}: {result[key]['error']}")
```
```

--------------------------------

### headroom rollout status --json

Source: https://headroom-docs.vercel.app/docs/runtime-rollouts

CLI command to inspect a supplied configuration without starting the proxy. Output is machine-readable JSON.

```bash
headroom rollout status --json
```

--------------------------------

### headroom learn command examples

Source: https://headroom-docs.vercel.app/docs/failure-learning

Shows various ways to run `headroom learn`: dry-run, apply to local files, specify a project, analyze all projects, and target a team-shared file.

```bash
# See recommendations for current project (dry-run, no changes)
headroom learn

# Write recommendations to CLAUDE.local.md and MEMORY.md
headroom learn --apply

# Analyze a specific project
headroom learn --project ~/my-project --apply

# Analyze all projects
headroom learn --all --apply

# Write to the team-shared CLAUDE.md instead of CLAUDE.local.md
headroom learn --apply --target CLAUDE.md
```

--------------------------------

### AnthropicProvider usage example

Source: https://headroom-docs.vercel.app/docs/api-reference

Shows how to instantiate AnthropicProvider with a custom Anthropic client and count messages using the API for accurate counts.

```python
from headroom import AnthropicProvider
from anthropic import Anthropic

provider = AnthropicProvider(
    client=Anthropic(),
)

counter = provider.get_token_counter("claude-3-5-sonnet-latest")
tokens = counter.count_messages(messages)  # Accurate count via API
```

--------------------------------

### Install Python 3.13 via Homebrew and retry uv tool install

Source: https://headroom-docs.vercel.app/docs/installation

If Python 3.13 is missing, install it with Homebrew or let uv download a managed interpreter. Then retry the uv tool install with the --python 3.13 flag.

```bash
brew install python@3.13
uv tool install --python 3.13 "headroom-ai[all]"
```

--------------------------------

### Windows PowerShell one-line install

Source: https://headroom-docs.vercel.app/docs/docker-install

Installs Headroom via Docker on Windows using PowerShell's irm and iex. Requires Docker to be installed and available.

```powershell
irm https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.ps1 | iex
```

--------------------------------

### Antigravity IDE

Source: https://headroom-docs.vercel.app/docs/proxy

Instructions for routing Google's Antigravity IDE model traffic through the proxy, including setup commands and MCP registration.

```APIDOC
## Antigravity IDE

### Description
Instructions for routing Google's Antigravity IDE model traffic through the proxy, including setup commands and MCP registration.

### Commands
- `headroom wrap antigravity` - Start proxy + print Antigravity setup instructions
- `headroom mcp install --agent antigravity` - Register the Headroom MCP server in Antigravity

### Details
`wrap antigravity` prints a custom OpenAI-compatible model-provider base URL to add in Antigravity's model-provider settings; Antigravity fetches the model list from GET /v1/models on its own. Native Cloud Code Assist traffic (google-antigravity clients) is accepted on POST /v1internal:streamGenerateContent and routed upstream like any other Cloud Code request.

MCP registration writes to Antigravity's global mcp_config.json under ~/.gemini/ (preferring the install's current location when one already exists) and refuses to overwrite a config file that does not parse as JSON.
```

--------------------------------

### Quick start with HeadroomStrandsModel

Source: https://headroom-docs.vercel.app/docs/strands

Wrap a BedrockModel with HeadroomStrandsModel to enable conversation compression. The agent call triggers compression, and total tokens saved are printed.

```python
from strands import Agent
from strands.models.bedrock import BedrockModel
from headroom.integrations.strands import HeadroomStrandsModel

model = BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0")
optimized = HeadroomStrandsModel(wrapped_model=model)

agent = Agent(model=optimized)
response = agent("Investigate the production incident")

print(f"Tokens saved: {optimized.total_tokens_saved}")
```

--------------------------------

### headroom wrap opencode with all options

Source: https://headroom-docs.vercel.app/docs/opencode

Full command showing all wrap options, including --openai-api-url to route through a third-party OpenAI-compatible provider. Without it, traffic goes to the default upstream and a non-OpenAI key is rejected with '401 Incorrect API key provided'.

```bash
headroom wrap opencode \
  --port 8787 \
  --no-mcp \
  --no-serena \
  --code-graph \
  --no-proxy \
  --openai-api-url https://api.deepseek.com/v1 \
  --learn \
  --memory \
  --backend anthropic \
  --anyllm-provider ... \
  --region ... \
  -- <opencode args>
```

--------------------------------

### Quick start with withHeadroom

Source: https://headroom-docs.vercel.app/docs/anthropic-sdk

Wrap an Anthropic client with withHeadroom to auto-compress messages on every messages.create() call. The response format is identical to the unwrapped client.

```typescript
import { withHeadroom } from 'headroom-ai/anthropic';
import Anthropic from '@anthropic-ai/sdk';

const client = withHeadroom(new Anthropic());

const response = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  messages: longConversation,
  max_tokens: 1024,
});
```

--------------------------------

### Validate client setup (Python)

Source: https://headroom-docs.vercel.app/docs/api-reference

Checks configuration validity. Returns a dict with 'valid' boolean and per-component status dicts. Prints errors for invalid components.

```Python
result = client.validate_setup()
# Returns {"valid": bool, "provider": {...}, "storage": {...},
#          "config": {...}, "cache_optimizer": {...}}, each with "ok"/"error"
if not result["valid"]:
    for key in ("provider", "storage", "config", "cache_optimizer"):
        if not result[key]["ok"]:
            print(f"  - {key}: {result[key]['error']}")
```

--------------------------------

### Configure ImageCompressor

Source: https://headroom-docs.vercel.app/docs/image-compression

Shows how to instantiate ImageCompressor with model_id, use_siglip, and device options. The device can be 'auto', 'cuda', 'cpu', or 'mps'.

```python
from headroom.image import ImageCompressor

compressor = ImageCompressor(
    model_id="chopratejas/technique-router",  # HuggingFace model
    use_siglip=True,   # Enable image analysis
    device="cuda",     # Use GPU if available (auto, cuda, cpu, mps)
)
```

--------------------------------

### Set LiteLLM Vertex environment variables and run proxy

Source: https://headroom-docs.vercel.app/docs/proxy

Export GOOGLE_APPLICATION_CREDENTIALS, VERTEXAI_PROJECT, and VERTEXAI_LOCATION, then run the proxy with --backend vertex_ai. If VERTEXAI_PROJECT is unset, requests may silently bill the wrong GCP project.

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json  # or use ADC
export VERTEXAI_PROJECT=<your-gcp-project>
export VERTEXAI_LOCATION=us-central1

headroom proxy --backend vertex_ai --region us-central1
```

--------------------------------

### Install Headroom CLI with uv tool

Source: https://headroom-docs.vercel.app/docs/installation

Installs the headroom CLI in an isolated app environment using uv tool. The --python 3.13 flag ensures a wheel-supported interpreter. After installation, verify with headroom --version.

```bash
uv tool install --python 3.13 "headroom-ai[all]"
headroom --version
```

--------------------------------

### Configure Embedder Backends (ONNX, OpenAI, Ollama)

Source: https://headroom-docs.vercel.app/docs/memory

Shows how to create a MemoryConfig with different embedder backends. ONNX is recommended for speed and privacy; OpenAI offers higher quality at a cost; Ollama uses a local server. Note that EmbedderBackend.LOCAL requires PyTorch (~2 GB), so ONNX is preferred.

```python
from headroom.memory import MemoryConfig, EmbedderBackend

# ONNX embeddings (recommended -- fast, free, private; ~30 MB int8-quantized)
# Note: EmbedderBackend.LOCAL requires PyTorch (~2 GB); use ONNX instead.
config = MemoryConfig(
    embedder_backend=EmbedderBackend.ONNX,
    embedder_model="BAAI/bge-small-en-v1.5",
)

# OpenAI embeddings (higher quality, costs money)
config = MemoryConfig(
    embedder_backend=EmbedderBackend.OPENAI,
    openai_api_key="sk-...",
    embedder_model="text-embedding-3-small",
)

# Ollama embeddings (local server, many models)
config = MemoryConfig(
    embedder_backend=EmbedderBackend.OLLAMA,
    ollama_base_url="http://localhost:11434",
    embedder_model="nomic-embed-text",
)
```

--------------------------------

### Upgrade pip

Source: https://headroom-docs.vercel.app/docs/installation

Upgrade pip to the latest version to resolve editable install failures with `pip install -e`.

```bash
python3 -m pip install --upgrade pip
```

--------------------------------

### Install pinned Headroom release with pipx

Source: https://headroom-docs.vercel.app/docs/installation

Installs a specific Headroom version by replacing <version> with the desired release number.

```bash
pipx install --python python3.13 "headroom-ai[all]==<version>"
```

--------------------------------

### Build and install OpenClaw plugin from source

Source: https://headroom-docs.vercel.app/docs/openclaw

Run these commands from the plugin directory to build and link the plugin for local development. The --dangerously-force-unsafe-install flag is required for linking. The plugin checks launchers in this order: PATH, local npm bin, global npm, python.

```bash
cd plugins/openclaw
npm install
npm run build
openclaw plugins install --dangerously-force-unsafe-install --link .
```

--------------------------------

### Set up HeadroomDocumentCompressor

Source: https://headroom-docs.vercel.app/docs/langchain

Creates a HeadroomDocumentCompressor with max_documents=10, min_relevance=0.3, and prefer_diverse=True for MMR-style diversity. Compresses retrieved documents against the query.

```python
from headroom.integrations import HeadroomDocumentCompressor

compressor = HeadroomDocumentCompressor(
    max_documents=10,
    min_relevance=0.3,
    prefer_diverse=True,   # MMR-style diversity
)

docs = compressor.compress_documents(retrieved_docs, "What is Python?")
```

--------------------------------

### Install Python 3.13 with Homebrew

Source: https://headroom-docs.vercel.app/docs/installation

If you need a newer Python version on macOS with Homebrew, install Python 3.13 using this command.

```bash
brew install python@3.13
```

--------------------------------

### Run Headroom proxy with a local Bedrock gateway

Source: https://headroom-docs.vercel.app/docs/proxy

Starts Headroom proxy with --bedrock-api-url pointing to a local gateway (e.g., LiteLLM, LocalStack). The client's Bedrock endpoint must be set to Headroom's address. Routes are only registered when --bedrock-api-url or BEDROCK_TARGET_API_URL is set.

```bash
headroom proxy --bedrock-api-url http://127.0.0.1:4000
# then point the client's Bedrock endpoint at Headroom:
AWS_ENDPOINT_URL_BEDROCK_RUNTIME=http://127.0.0.1:8787 your-bedrock-client
```

--------------------------------

### Persistent watchdog task with headroom install apply

Source: https://headroom-docs.vercel.app/docs/persistent-installs

Installs a scheduled recovery path instead of a traditional always-running service, targeting claude and codex.

```bash
headroom install apply --preset persistent-task --providers manual --target claude --target codex
```

--------------------------------

### Reproduce Headroom benchmarks

Source: https://headroom-docs.vercel.app/docs/benchmarks

Clone the Headroom repository, install with evals and html extras, run evaluation tests, and execute the latency benchmark script to reproduce the latency and compression-ratio tables.

```bash
git clone https://github.com/headroomlabs-ai/headroom.git
cd headroom
pip install -e ".[evals,html]"
pytest tests/test_evals/ -v -s

# Latency and compression-ratio tables above
python benchmarks/bench_latency.py
```

--------------------------------

### Install separate LangChain provider packages

Source: https://headroom-docs.vercel.app/docs/langchain

Provider packages are separate, as in LangChain itself. Install langchain-anthropic for ChatAnthropic, langchain for create_agent and init_chat_model, and langchain-classic for ContextualCompressionRetriever.

```bash
pip install langchain-anthropic         # ChatAnthropic
pip install langchain                   # create_agent, init_chat_model
pip install langchain-classic           # ContextualCompressionRetriever
```

--------------------------------

### Start the Headroom proxy for DeepSeek

Source: https://headroom-docs.vercel.app/docs/opencode-deepseek

Starts the Headroom proxy on port 8787, pointing to the DeepSeek API. The proxy auto-detects api.deepseek.com and labels itself 'DeepSeek' on the dashboard.

```bash
headroom proxy \
  --port 8787 \
  --openai-api-url https://api.deepseek.com/v1
```

--------------------------------

### Before and After Code Compression Example

Source: https://headroom-docs.vercel.app/docs/code-compression

Shows a full source file before compression and the compressed version where the function body is replaced with a comment and pass statement. The signature and docstring are preserved.

```python
# Before (full source file)
def process_data(items: List[str]) -> Dict[str, int]:
    """Process items and count occurrences."""
    result = {}
    for item in items:
        item = item.strip().lower()
        if item in result:
            result[item] += 1
        else:
            result[item] = 1
    return result

# After (signature preserved, body compressed)
def process_data(items: List[str]) -> Dict[str, int]:
    """Process items and count occurrences."""
    result = {}
    for item in items:
    # ... (5 lines compressed)
    pass
```

--------------------------------

### Basic Usage (Python)

Source: https://headroom-docs.vercel.app/docs/simulation

Simulate compression using the client.chat.completions.simulate() method. It returns a plan object with waste signals, allowing you to preview compression without an LLM call.

```Python
plan = client.chat.completions.simulate(
    model="gpt-4o",
    messages=messages,
)

waste = plan.waste_signals  # dict[str, int]
print(f"JSON bloat:     {waste['json_bloat']} tokens")
print(f"HTML noise:     {waste['html_noise']} tokens")
print(f"Whitespace:     {waste['whitespace']} tokens")
print(f"Dynamic dates:  {waste['dynamic_date']} tokens")
print(f"Repetition:     {waste['repetition']} tokens")
```

--------------------------------

### Fix C++ compilation error on Linux and macOS

Source: https://headroom-docs.vercel.app/docs/troubleshooting

Install build tools and then pip install headroom-ai. For Linux/Debian-based systems use apt-get, for macOS use xcode-select.

```bash
# Linux / Debian-based (including Docker)
apt-get install -y build-essential && pip install headroom-ai

# macOS (Xcode command line tools)
xcode-select --install && pip install headroom-ai
```
Tokens:
Raw