Files
headroom/wiki/quickstart.md
Tejas ChopraandClaude Opus 5 27bdc2a899 docs(wiki): correct the unpublished tree, and remove invented telemetry (#3390)
`wiki/` **is not published anywhere.** `.github/workflows/docs.yml` says
so in its own header, no mkdocs or sphinx config exists, and `wiki/**`
sits in `paths-ignore` for CI — changes there don't even run a build. It
survives as pending-migration reference material for contributors.

That's why this is separate from the published-site work in #3388:
nothing here reaches a user through `docs.headroomlabs.ai`. It still
matters, because a contributor migrating a page would carry its errors
across, and because the repo is public.

## The finding that justifies this PR on its own

`wiki/benchmarks.md` carried an entire **invented "Production Telemetry"
section**, presented as real-world fleet data:

> real-world production telemetry from 250+ active proxy instances …
**52ms median overhead** … **1.4 billion tokens saved** across 249
instances

Plus P90/P99 timings, ~$4,000 saved, an OS split, a version-share
breakdown, and a dated collection window of March 30 – April 2, 2026.

A repo-wide grep for those figures **matches only that one file.** No
script, test or fixture produces them. The published benchmarks page
never carried the section, so the site owner had already excised it.

Removed rather than re-estimated. The per-category ranges hanging off it
(4.8%, 40–80%, 83–94%, 85–94%, 60–76%) went with it and now point at the
concrete compression table on the same page.

The same page also described `HEADROOM_TELEMETRY` as the opt-in switch
governing fleet-wide numbers. Fleet data would come from
`HEADROOM_BEACON` — a **separate switch that defaults ON**. That note is
gone with the section it footnoted; the accurate description of both
switches shipped to the live site in #3388.

## Other corrections, each verified against source

- **`wiki/agno.md`** constructed `HeadroomAgnoModel(config=...)`; the
field is `headroom_config` (`integrations/agno/model.py:135`). The
sibling `HeadroomPreHook` genuinely does take `config`, which is how
they got conflated.
- **`wiki/ccr.md`** documented CLI flags that don't exist, and a dead
demo script.
- **`wiki/image-compression.md`** had two broken CLI examples.
- **`wiki/getting-started.md`** used `plan.transforms_applied`;
`SimulationResult` exposes `transforms`. (`CompressResult` really does
have `transforms_applied` — two different result types, easy to cross.)
- **`wiki/cli.md`** documents 15 of ~27 top-level commands; an audit
note now says so rather than implying completeness.

## Disposition, for whoever picks up the migration

`wiki/cli.md` is the highest-value page to port — no site page is a full
CLI reference, and `docs.yml` names it as the reason `wiki/` still
exists. `wiki/integration-guide.md` and `wiki/configuration.md` also
cover ground the site doesn't.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 15:53:02 +05:30

374 lines
8.4 KiB
Markdown

# Quickstart Guide
Get Headroom running in 5 minutes with these copy-paste examples.
---
## Installation
**CLI on macOS Apple Silicon/Linux with uv:**
```bash
uv tool install --python 3.13 "headroom-ai[all]"
headroom --version
```
Use `uv tool update-shell` if the install succeeds but `headroom` is not on
`PATH`.
**Python project / virtualenv:**
```bash
# Core only (minimal dependencies)
pip install headroom-ai
# With proxy server
pip install "headroom-ai[proxy]"
# Everything
pip install "headroom-ai[all]"
```
**TypeScript / Node.js:**
```bash
npm install headroom-ai
```
**Docker-native:**
```bash
curl -fsSL https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.sh | bash
```
See [Docker-native install](docker-install.md) if you want Docker to provide the Headroom runtime while your agent CLIs stay on the host.
**Persistent background runtime:**
```bash
headroom install apply --preset persistent-service --providers auto
```
See [Persistent Installs](persistent-installs.md) if you want Headroom to stay up in the background and be reused by `wrap`.
---
## Option 1: Proxy Server (Zero Code Changes)
The fastest way to start saving tokens. Works with any OpenAI-compatible client.
### Step 1: Start the Proxy
```bash
headroom proxy --port 8787
```
### Step 2: Verify It's Running
```bash
curl http://localhost:8787/health
# Expected: {"status":"healthy","ready":true,"config":{"backend":"anthropic",...},...}
```
### Step 3: Point Your Client
```bash
# Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude
# GitHub Copilot CLI (default Anthropic-style proxy route)
headroom wrap copilot -- --model claude-sonnet-4-20250514
# Cursor / Continue / any OpenAI client
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
# Python
export OPENAI_BASE_URL=http://localhost:8787/v1
python your_script.py
```
### Step 4: Check Savings
```bash
curl http://localhost:8787/stats
# {"requests_total": 42, "tokens_saved_total": 125000, ...}
```
---
## Option 2: Python SDK
Wrap your existing client for fine-grained control.
### Basic Example
```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']}")
```
### With Tool Outputs (Where Savings Happen)
```python
from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI
import json
client = HeadroomClient(
original_client=OpenAI(),
provider=OpenAIProvider(),
default_mode="optimize",
)
# Simulate a conversation with large tool outputs
messages = [
{"role": "system", "content": "You analyze search results."},
{"role": "user", "content": "Search for Python tutorials."},
{
"role": "assistant",
"content": None,
"tool_calls": [
{
"id": "call_1",
"type": "function",
"function": {"name": "search", "arguments": '{"q": "python"}'},
}
],
},
{
"role": "tool",
"tool_call_id": "call_1",
# This is where Headroom shines - compressing large outputs
"content": json.dumps(
{"results": [{"title": f"Result {i}", "score": 100 - i} for i in range(500)]}
),
},
{"role": "user", "content": "What are the top 3 results?"},
]
# Headroom compresses the 500 results to ~20, keeping the most relevant
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
)
print(response.choices[0].message.content)
```
### Simulate Before Sending
Preview optimizations without making an API call:
```python
# See what would happen without calling the API
plan = client.chat.completions.simulate(
model="gpt-4o",
messages=messages,
)
print(f"Tokens before: {plan.tokens_before}")
print(f"Tokens after: {plan.tokens_after}")
print(
f"Would save: {plan.tokens_saved} tokens ({plan.tokens_saved / plan.tokens_before * 100:.0f}%)"
)
print(f"Transforms: {plan.transforms}")
print(f"Estimated savings: {plan.estimated_savings}")
```
---
## Option 3: Anthropic SDK
```python
from headroom import HeadroomClient, AnthropicProvider
from anthropic import Anthropic
client = HeadroomClient(
original_client=Anthropic(),
provider=AnthropicProvider(),
default_mode="optimize",
)
# Use Anthropic-style API
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude!"},
],
)
print(response.content[0].text)
```
---
## Verify It's Working
### Method 1: Enable Logging
```python
import logging
logging.basicConfig(level=logging.INFO)
# Now you'll see:
# INFO:headroom.transforms.pipeline:Pipeline complete: 45000 -> 4500 tokens (saved 40500, 90.0% reduction)
# INFO:headroom.transforms.smart_crusher:SmartCrusher: keeping 15 of 500 items
```
### Method 2: Check Session Stats
```python
stats = client.get_stats()
print(stats)
# {
# "session": {"requests_total": 10, "tokens_saved_total": 5000, ...},
# "config": {"mode": "optimize", "provider": "openai", ...},
# "transforms": {"smart_crusher_enabled": True, ...}
# }
```
### Method 3: Validate Setup
```python
result = client.validate_setup()
if not result["valid"]:
print("Setup issues:", result)
else:
print("Setup OK!")
print(f"Provider: {result['provider']['name']}")
print(f"Storage: {result['storage']['url']}")
```
---
## Common Configuration
### Adjust Compression
```python
from headroom import HeadroomClient, OpenAIProvider, HeadroomConfig
config = HeadroomConfig()
# Keep more items after compression (default: 15)
config.smart_crusher.max_items_after_crush = 30
# Only compress if tool output has > 500 tokens (default: 200)
config.smart_crusher.min_tokens_to_crush = 500
client = HeadroomClient(
original_client=OpenAI(),
provider=OpenAIProvider(),
config=config, # Pass custom config
default_mode="optimize",
)
```
### Skip Compression for Specific Tools
```python
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
headroom_tool_profiles={
"database_query": {"skip_compression": True}, # Never compress
"search": {"max_items": 50}, # Keep more items
},
)
```
### Audit Mode (Observe Only)
```python
# Start in audit mode - see what WOULD be optimized
client = HeadroomClient(
original_client=OpenAI(),
provider=OpenAIProvider(),
default_mode="audit", # No modifications, just logging
)
# Override per-request
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
headroom_mode="optimize", # Enable for this request only
)
```
---
## What Gets Optimized?
| Content Type | What Headroom Does | Typical Savings |
|--------------|-------------------|-----------------|
| **Tool outputs with lists** | Keeps errors, anomalies, high-score items | 70-90% |
| **Repeated search results** | Deduplicates and samples | 60-80% |
| **Long conversations** | Compresses the newest tool output / user turn only (live-zone-only); never drops messages | varies |
| **System prompts with dates** | Stabilizes for cache hits | Cache savings |
---
## Next Steps
- **[Configuration Reference](configuration.md)** - All configuration options
- **[Transform Reference](transforms.md)** - How each transform works
- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions
- **[Examples](../examples/)** - More complete examples
---
## Quick Troubleshooting
### "No token savings"
```python
# 1. Check mode
stats = client.get_stats()
print(stats["config"]["mode"]) # Should be "optimize"
# 2. Enable logging to see what's happening
import logging
logging.basicConfig(level=logging.DEBUG)
```
### "High latency"
```python
# Use BM25 instead of embeddings for faster relevance scoring
config.smart_crusher.relevance.tier = "bm25"
```
### "Compression too aggressive"
```python
# Keep more items
config.smart_crusher.max_items_after_crush = 50
```
See [Troubleshooting Guide](troubleshooting.md) for more solutions.