### Install Dependencies and Run Examples

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/README.md

Instructions for installing project dependencies in development mode and running any example script from the repository root.

```bash
# Install dependencies
pip install -e ".[dev]"

# Run any example
python examples/<example_name>.py
```

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

### Install Headroom and Start Proxy

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/integration-guide.md

Install the Headroom AI package with all extras and start the proxy server on a specified port. This is the initial setup for using the proxy.

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

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

### Run Examples with tsx

Source: https://github.com/headroomlabs-ai/headroom/blob/main/sdk/typescript/examples/README.md

Navigate to the SDK directory, install dependencies, and run specific example files using tsx.

```bash
cd sdk/typescript
npm install
npx tsx examples/<filename>.ts
```

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

### Start Headroom Proxy (TypeScript SDK)

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/quickstart.mdx

Install the proxy and start it on the specified port. The TypeScript SDK requires this local proxy to run.

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

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

### Install and Run Headroom Proxy with NPM

Source: https://github.com/headroomlabs-ai/headroom/blob/main/plugins/openclaw/README.md

Use this command to install the Headroom CLI globally and start the proxy locally.

```bash
npm install -g headroom-ai
headroom proxy --host 127.0.0.1 --port 8787
```

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

### Install Headroom AI

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/07-context-compression.ipynb

Install the Headroom AI library with all extras. This is a one-time setup step.

```python
# Install headroom (one-time)
# !pip install "headroom-ai[all]"
```

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

### Install and Run Headroom Proxy with Pip

Source: https://github.com/headroomlabs-ai/headroom/blob/main/plugins/openclaw/README.md

Use this command to install the necessary package and start the Headroom proxy locally.

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

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

### Start Headroom Proxy and Use SDK

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/installation.mdx

Install the proxy and run it on port 8787. Then, import and use the `compress` function from the SDK, pointing it to the running proxy.

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

```typescript
import { compress } from 'headroom-ai';

const result = await compress(messages, {
  baseUrl: 'http://localhost:8787',
});
```

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

### Install OpenClaw Plugin

Source: https://github.com/headroomlabs-ai/headroom/blob/main/plugins/openclaw/README.md

Use this command for a recommended one-command setup of the OpenClaw plugin.

```bash
headroom wrap openclaw
```

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

### Start Headroom Installation

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/cli.md

Starts a Headroom deployment profile that has already been installed, without reapplying any configuration changes. This is useful for resuming a stopped service.

```bash
headroom install start
```

```bash
headroom install start --profile default
```

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

### First-time Setup for Headroom Python Bindings

Source: https://github.com/headroomlabs-ai/headroom/blob/main/RUST_DEV.md

This snippet outlines the steps to set up a Python virtual environment, install Maturin, and build the headroom Python extension module for development.

```bash
python3.11 -m venv /tmp/hr-rust-venv
source /tmp/hr-rust-venv/bin/activate
pip install maturin
cd crates/headroom-py
maturin develop           # editable dev build, installs headroom._core
cd /tmp                   # IMPORTANT: step out of the repo root first
python -c "from headroom._core import hello; print(hello())"
# => headroom-core
```

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

### Install and Run Development Tools

Source: https://github.com/headroomlabs-ai/headroom/blob/main/agent-evals/README.md

Commands to set up the development environment, install dependencies, and run linting/testing gates.

```bash
cd agent-evals
python -m venv .venv && source .venv/bin/activate
make install        # pip install -e ".[dev,stats]"
make gate           # ruff + mypy + pytest  (the agent-evals push gate)
agent-evals show-config
```

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

### Headroom Install Command Help

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/cli.md

Details the commands for installing and managing persistent Headroom deployments, including applying, removing, starting, and stopping deployments.

```text
Usage: headroom install [OPTIONS] COMMAND [ARGS]...

  Install and manage persistent Headroom deployments.

Options:
  -?, --help  Show this message and exit.

Commands:
  apply    Install a persistent Headroom deployment.
  remove   Remove a persistent deployment and undo managed config.
  restart  Restart a persistent deployment.
  start    Start a persistent deployment.
  status   Show persistent deployment status.
  stop     Stop a persistent deployment.

```

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

### Install Headroom and LiteLLM

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/litellm.mdx

Install the necessary libraries for Headroom AI and LiteLLM.

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

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

### Install Headroom on Windows with All Extras

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/installation.mdx

Install Headroom with all extras on Windows using uv or pip, ensuring the MSVC toolchain and Rust are installed.

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

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

### Initialize HeadroomClient with Anthropic

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/sdk.md

Instantiate the HeadroomClient with an Anthropic original client and provider. This example also shows a basic message creation call. Ensure the 'anthropic' library is installed.

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

client = HeadroomClient(
    original_client=Anthropic(),
    provider=AnthropicProvider(),
)

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
```

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

### Install Headroom with OTEL Support

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/metrics.md

Install the necessary packages for Headroom to export OTEL metrics. This command installs the proxy and OTEL extras.

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

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

### Install Headroom MCP Client

Source: https://github.com/headroomlabs-ai/headroom/blob/main/README.md

Install the Headroom MCP client using the provided CLI command.

```bash
headroom mcp install
```

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

### Install Headroom AI with All Features (Python)

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/index.md

Install Headroom AI with all optional dependencies for Python using pip. This is the recommended installation for full functionality.

```bash
pip install "headroom-ai[all]"         # Everything (recommended)
```

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

### Install Headroom MCP Client

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/mcp.mdx

Installs the Headroom MCP client. Use --proxy-url for a custom proxy or --force to overwrite existing installations.

```bash
# Install (registers with Claude Code)
headroom mcp install
```

```bash
headroom mcp install --proxy-url http://host:9000  # Custom proxy URL
```

```bash
headroom mcp install --force                        # Overwrite existing
```

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

### Install headroom-opencode

Source: https://github.com/headroomlabs-ai/headroom/blob/main/plugins/opencode/README.md

Install the headroom-opencode package using npm.

```bash
npm install headroom-opencode
```

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

### Install and Enable headroom-oauth2

Source: https://github.com/headroomlabs-ai/headroom/blob/main/plugins/headroom-oauth2/README.md

Install the package using pip and enable the extension when running the Headroom proxy.

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

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

### Install Headroom.ai with npm/pnpm/bun

Source: https://github.com/headroomlabs-ai/headroom/blob/main/llms.txt

Install Headroom.ai for TypeScript/Node.js projects using npm, pnpm, or bun.

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

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

```bash
bun add headroom-ai
```

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

### Clone and Set Up Development Environment

Source: https://github.com/headroomlabs-ai/headroom/blob/main/CONTRIBUTING.md

Clone the repository, set up a virtual environment, and install development dependencies. Ensure Node.js 18+ is installed for commitlint hooks. Upgrade pip if necessary.

```bash
git clone https://github.com/chopratejas/headroom.git
cd headroom
python -m venv .venv && source .venv/bin/activate
node --version  # Node 18+ required for commitlint hooks
python -m pip install --upgrade pip
python -m pip install -e ".[dev,relevance,proxy]"
python -m pytest
```

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

### Headroom Install Commands

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/persistent-installs.mdx

These commands are used to manage persistent installations. They cover applying configurations, checking status, starting, stopping, restarting, and removing installations.

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

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

### Run Basic OpenAI Integration Example

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/README.md

Demonstrates basic integration with the OpenAI client. Ensure your OPENAI_API_KEY is exported.

```bash
export OPENAI_API_KEY='your-key'
python examples/basic_usage.py
```

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

### Start Headroom Proxy with Logging and Budget

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/proxy.mdx

Configure the proxy to log to a file and set a daily budget limit.

```bash
headroom proxy \
  --log-file /var/log/headroom.jsonl \
  --budget 100.0
```

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

### Install Headroom Proxy Service

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/deployment/macos-launchagent/README.md

Installs the headroom proxy service as a LaunchAgent. This script handles the setup for automatic startup and crash recovery.

```bash
./install.sh
```

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

### Reproduce Benchmark Results

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/benchmarks.mdx

Clone the repository, install dependencies, and run the evaluation tests to reproduce benchmark results. Ensure you have Python and pip installed.

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

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

### Full Compression Pipeline Example

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/compression.md

Demonstrates configuring UniversalCompressor for aggressive compression using multiple features including Magika, LLMLingua, and CCR. Shows compression of JSON content and prints the results.

```python
from headroom.compression import UniversalCompressor, UniversalCompressorConfig

# Configure for aggressive compression
config = UniversalCompressorConfig(
    compression_ratio_target=0.25,  # Keep 25%
    use_magika=True,
    use_llmlingua=True,
    ccr_enabled=True,
)

compressor = UniversalCompressor(config=config)

# Compress JSON API response
json_content = """
{
    "users": [
        {"id": "usr_123", "name": "Alice", "bio": "Software engineer..."},
        {"id": "usr_456", "name": "Bob", "bio": "Product manager..."
    ],
    "total": 2,
    "page": 1
}
"""

result = compressor.compress(json_content)

print(f"Type: {result.content_type}")          # ContentType.JSON
print(f"Handler: {result.handler_used}")        # json
print(f"Saved: {result.savings_percentage:.0f}%")  # ~60%
print(f"Structure: {result.preservation_ratio:.0%} preserved")  # ~40%
print(f"CCR Key: {result.ccr_key}")             # For retrieval
```

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

### Basic Headroom Client Setup

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/quickstart.md

Initialize the HeadroomClient by wrapping an existing OpenAI client. Set the default mode to 'optimize' for automatic token savings. Use the wrapped client just like the original OpenAI client.

```python
from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

# Create wrapped client
client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
)

# Use exactly like OpenAI client
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(response.choices[0].message.content)

# Check what happened
stats = client.get_stats()
print(f"Tokens saved: {stats['session']['tokens_saved_total']}")
```

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

### Headroom Proxy Command Help

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/cli.md

Shows options and usage for starting the optimization proxy server. Useful for configuring the proxy's port or enabling passthrough mode.

```text
Usage: headroom proxy [OPTIONS]

  Start the optimization proxy server.

  Examples:
      headroom proxy                    Start proxy on port 8787
      headroom proxy --port 8080        Start proxy on port 8080
      headroom proxy --no-optimize      Passthrough mode (no optimization)

  Usage with Claude Code:
      ANTHROPIC_BASE_URL=http://localhost:8787 claude

  Usage with OpenAI-compatible clients:
      OPENAI_BASE_URL=http://localhost:8787/v1 your-app

```

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

### Install and Wrap Claude Code with Headroom

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/claude-code-vertex.mdx

Install the Headroom AI library and use the 'headroom wrap claude' command to start the Headroom proxy. This automatically configures Claude Code to use Headroom's Vertex endpoint.

```bash
pip install headroom-ai
headroom wrap claude
```

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

### Check Pipx Python Environment

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/installation.mdx

List installed pipx applications and the Python versions they use to verify environment setup.

```bash
pipx list
```

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

### Install Headroom with All Extras

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/installation.mdx

Install Headroom with all available optional features, including proxy, ML, code, memory, and more, using the '[all]' extra.

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

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

### Get Headroom Path

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/macos-deployment.md

Determines the installation path of the headroom executable. This path is needed to update the LaunchAgent plist configuration.

```bash
command -v headroom
```

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

### Get Proxy Health Status Response

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/proxy.mdx

Example JSON response from the /health endpoint, indicating the proxy's operational status and performance statistics.

```json
{
  "status": "healthy",
  "optimize": true,
  "stats": {
    "total_requests": 42,
    "tokens_saved": 15000,
    "savings_percent": 45.2
  }
}
```

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

### Proxy-backed Compression Setup

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/mcp.mdx

Use this command to start the proxy and then launch Claude with the proxy URL. This enables automatic compression of normal Claude Code traffic.

```bash
headroom proxy

ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude
```

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

### Restart Headroom Installation

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/cli.md

Restarts a selected Headroom deployment profile by first stopping the runtime and then starting it again. This is useful for applying certain updates or recovering from a stalled state.

```bash
headroom install restart
```

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

### Set API Keys for Examples

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/README.md

Shows how to set environment variables for OpenAI and Anthropic API keys, which are required for certain examples.

```bash
export OPENAI_API_KEY='sk-...'
export ANTHROPIC_API_KEY='sk-ant-...'
```

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

### Configure Custom LaunchAgent Schedule

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/macos-deployment.md

Adds a schedule to a macOS LaunchAgent plist file to run the proxy only during specified business hours. This example sets the start time to 9:00 AM.

```xml
<!-- Add to plist -->
<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>9</integer>
    <key>Minute</key>
    <integer>0</integer>
</dict>
```

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

### Run Smart vs. Naive Evaluation Example

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/README.md

Compares Headroom's SmartCrusher against naive truncation. Ensure your OPENAI_API_KEY is exported.

```bash
export OPENAI_API_KEY='your-key'
python examples/smart_vs_naive_eval.py
```

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

### Basic Compression with Python

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/how-compression-works.mdx

Import the `compress` function from the `headroom` library to compress data. This example demonstrates basic usage and how to retrieve the compressed output and savings percentage.

```python
from headroom import compress

result = compress(content)
print(result.compressed)
print(f"Saved {result.savings_percentage:.0f}% tokens")
```

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

### Retrieve Original Content with headroom_retrieve

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/mcp.md

This example shows how to use the `headroom_retrieve` tool with a hash to get the original uncompressed content. The `query` parameter can be used to search within the retrieved content.

```json
Tool: headroom_retrieve

Parameters:
  - hash (required): Hash key from compression
  - query (optional): Search within the original to return only matching items

Returns:
  - original_content (full retrieval) or results (search)
  - source: "local" or "proxy"
```

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

### Install and Run Headroom Proxy

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/index.md

Install the Headroom AI package and run the proxy service. Point your tools to the proxy to automatically compress tokens.

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

```bash
# Point any tool at the proxy
ANTHROPIC_BASE_URL=http://localhost:8787 claude
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
```

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

### Example of Headroom Learned Patterns Markers

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/failure-learning.mdx

This markdown snippet shows the start and end markers used by Headroom to manage learned patterns within files. Content between these markers is automatically updated.

```markdown
<!-- headroom:learn:start -->
## Headroom Learned Patterns
*Auto-generated by `headroom learn` -- do not edit manually*
...
<!-- headroom:learn:end -->
```

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

### Quick Start: Optimize Strands Agent with Headroom

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/strands.mdx

Initialize a Strands Agent with a Headroom-optimized model for automatic message compression during agent interactions. This example demonstrates basic usage and how to access token savings.

```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}")
```

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

### Install and Run All Benchmarks

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/benchmarks.md

Clone the repository, install necessary dependencies including evaluation and HTML support, and then run all benchmark tests using pytest.

```bash
# Clone the repo
git clone https://github.com/chopratejas/headroom.git
cd headroom

# Install with eval dependencies
pip install -e ".[evals,html]"

# Run all benchmarks
pytest tests/test_evals/ -v -s
```

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

### Initialize Headroom Client (Python)

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/configuration.mdx

Set up the HeadroomClient in Python, specifying the original client, provider, default mode, cache optimizer, semantic cache, model context limits, and database store URL.

```python
from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),

    # Mode: "audit" (observe only) or "optimize" (apply transforms)
    default_mode="optimize",

    # Enable provider-specific cache optimization
    enable_cache_optimizer=True,

    # Enable query-level semantic caching
    enable_semantic_cache=False,

    # Override default context limits per model
    model_context_limits={
        "gpt-4o": 128000,
        "gpt-4o-mini": 128000,
    },

    # Database location (defaults to temp directory)
    # store_url="sqlite:////absolute/path/to/headroom.db",
)
```

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

### Quick Start: Wrap Agno Model with Headroom

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/agno.mdx

Wrap an Agno OpenAI model with HeadroomAgnoModel to enable automatic context compression. This example demonstrates basic agent usage and retrieving savings metrics.

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from headroom.integrations.agno import HeadroomAgnoModel

model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))
agent = Agent(model=model)

response = agent.run("What's the capital of France?")

print(f"Tokens saved: {model.total_tokens_saved}")
print(model.get_savings_summary())
# {'total_requests': 1, 'total_tokens_saved': 245, 'average_savings_percent': 12.3}
```

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

### Quick Start: Initialize Headroom-wrapped Anthropic Client

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/anthropic-sdk.mdx

Wrap your Anthropic client instance with `withHeadroom` to enable automatic message compression for `client.messages.create()` calls. This setup requires importing `withHeadroom` from `headroom-ai/anthropic` and the `Anthropic` 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,
});
```

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

### Initialize HeadroomClient with OpenAI

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/sdk.md

Instantiate the HeadroomClient with an OpenAI original client and provider. Ensure the 'openai' library is installed.

```python
from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
)
```

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

### Get Session Statistics with headroom_stats

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/mcp.md

This example outlines the information provided by the `headroom_stats` tool, including compression and retrieval counts, token savings, estimated costs, and recent events. It also details how sub-agent and proxy statistics are aggregated.

```json
Tool: headroom_stats

Returns:
  - compressions, retrievals, tokens_saved, savings_percent
  - estimated_cost_saved_usd
  - recent_events (last 10 compression/retrieval events)
  - sub_agents (stats from sub-agent MCP instances, if any)
  - combined (main + sub-agent totals)
  - proxy (request count, cache hits, cost saved — if proxy is running)
```

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

### validate_setup()

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/api-reference.mdx

Validate that the client is configured correctly and identify any issues.

```APIDOC
## validate_setup()

### Description
Validate that the client is configured correctly.

### Response
Returns a dictionary with a "valid" boolean field and an "issues" list if validation fails.

### Request Example
```python
result = client.validate_setup()
if not result["valid"]:
    for issue in result["issues"]:
        print(f"  - {issue}")
```
```

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

### Install act

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/releases.mdx

Installs the 'act' tool using winget. Optionally, 'actionlint' can also be installed for schema validation.

```bash
# Install act
winget install act

# Optional: install actionlint for schema validation
winget install actionlint
```

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

### Install Headroom with Agno Support

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/agno.md

Install Headroom with the Agno integration package. You will also need to install Agno separately.

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

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

### Configure Headroom Proxy with Command Line Options

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/configuration.mdx

Set up the headroom proxy using command-line options for port, host, compression mode, budget, and log file.

```bash
headroom proxy \
  --port 8787 \
  # Port to listen on
  --host 0.0.0.0 \
  # Host to bind to
  --mode token \
  # token compression mode; use cache for prefix-cache stability
  --budget 10.00 \
  # Daily budget limit in USD
  --log-file headroom.jsonl  # Log file path
```

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

### Install Headroom AI

Source: https://github.com/headroomlabs-ai/headroom/blob/main/README.md

Install Headroom AI using pip for Python or npm for Node.js/TypeScript. The `[all]` extra installs all optional dependencies.

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

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

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

### Run LangChain Compression Demo

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/README.md

Demonstrates full LangChain agent integration for compression. No API key is needed for this specific demo.

```bash
# No API key needed for compression demo
PYTHONPATH=. python -m examples.langchain_demo.show_compression
```

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

### Run Streaming Responses Example

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/README.md

Demonstrates streaming responses with optimization. Ensure your OPENAI_API_KEY is exported.

```bash
export OPENAI_API_KEY='your-key'
python examples/streaming_example.py
```

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

### Quick Start with HeadroomClient

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/sdk.md

Initialize and use the HeadroomClient with an OpenAI provider in optimize mode. This client can be used exactly like the original OpenAI client.

```python
from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

# Create wrapped client
client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
)

# Use exactly like the original client
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Hello!"},
    ],
)

print(response.choices[0].message.content)
```

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

### Validate Headroom Setup

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/metrics.md

Validate that your Headroom setup is correct. This function returns a dictionary indicating if the setup is valid and lists any issues found.

```python
result = client.validate_setup()

if result["valid"]:
    print("Setup is correct!")
else:
    print("Issues found:")
    for issue in result["issues"]:
        print(f"  - {issue}")
```

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

### Run Compression Demo (Bash)

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/langchain_demo/README.md

Execute a standalone demonstration of Headroom's compression capabilities without requiring an API key.

```bash
PYTHONPATH=. python -m examples.langchain_demo.show_compression
```

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

### Run Tabular Compression Demo

Source: https://github.com/headroomlabs-ai/headroom/blob/main/examples/README.md

Demonstrates tabular and spreadsheet compression on generated sample data. This example does not require an API key. It shows how CSV, markdown tables, and .xlsx workbooks are compressed, and how compact, all-unique data passes through.

```bash
python examples/tabular_compression_demo.py            # run all scenarios
python examples/tabular_compression_demo.py --write DIR # also save the sample files
```

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

### Install Headroom AI Core Library (Python)

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/index.md

Install the core Headroom AI library for Python using pip. This is the basic installation for Python projects.

```bash
pip install headroom-ai                # Core library (Python)
```

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

### Install Headroom MCP

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/mcp.md

Installs the Headroom MCP tool. Use --proxy-url for custom proxy configurations or --force to overwrite existing installations.

```bash
headroom mcp install                              # Default setup
```

```bash
headroom mcp install --proxy-url http://host:9000  # Custom proxy URL
```

```bash
headroom mcp install --force                       # Overwrite existing
```

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

### Local Development Install (Linked)

Source: https://github.com/headroomlabs-ai/headroom/blob/main/plugins/openclaw/README.md

For local development, install the plugin from the repository using npm and link it. This ensures local launcher detection aligns with runtime paths. The `--link` flag is used to create a symbolic link to the plugin directory.

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

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

### Install Headroom on Linux using Docker

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/docker-install.mdx

Use this command to install Headroom on Linux systems via a Docker-native wrapper. It downloads and executes an installation script.

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

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

### Quick Start with Headroom Memory

Source: https://github.com/headroomlabs-ai/headroom/blob/main/wiki/memory.md

Initialize the OpenAI client with `with_memory` to enable inline memory extraction. Use the client as usual; memory is automatically managed.

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

# One line - that's it
client = with_memory(OpenAI(), user_id="alice")

# Use exactly like normal
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "I prefer Python for backend work"}]
)
# Memory extracted INLINE - zero extra latency

# Later, in a new conversation...
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What language should I use?"}]
)
# → Response uses the Python preference from memory
```

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

### Install Headroom with Specific Extras

Source: https://github.com/headroomlabs-ai/headroom/blob/main/docs/content/docs/installation.mdx

Combine multiple specific extras like 'proxy', 'langchain', and 'ml' to install only the required functionalities.

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

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

### Install Plugin from dist/ (Linked)

Source: https://github.com/headroomlabs-ai/headroom/blob/main/plugins/openclaw/README.md

Install the plugin from the `dist/` directory within the plugin's folder by linking it. This is useful when working with the built output directly.

```bash
cd plugins/openclaw/dist
openclaw plugins install --dangerously-force-unsafe-install --link .
```