mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-10 14:27:00 -04:00

docs: use headroom-ai package name in install commands (#1014 ) (#1257 )

## Description

Install commands across the docs referenced the unpublished `headroom`
package instead of the published `headroom-ai`, so copy-pasted `pip
install` commands fail. This corrects them to `headroom-ai` (with
extras).

Closes #1014

## Type of Change

- [x] Documentation update

## Changes Made

- `wiki/getting-started.md`: corrected 4 `pip install headroom` commands
to `headroom-ai` (including the `[proxy]`, `[relevance]`, and `[all]`
extras).
- `docs/content/docs/claude-code-vertex.mdx`: fixed the install command
on line 37.
- `SECURITY.md`: fixed the install command on line 47.

## Testing

- [x] Manual verification

### Test Output

```text
$ rg -n "pip install headroom\b" docs wiki SECURITY.md
(no matches — all bare `headroom` install commands now use `headroom-ai`)
```

## Real Behavior Proof

- Environment: Windows 11, repo working tree on branch
fix/docs-1014-headroom-ai-pkg
- Exact command / steps: Grepped the docs tree for `pip install
headroom` before and after the edits.
- Observed result: Before, several occurrences referenced the
unpublished `headroom`; after, only `headroom-ai` remains (the spec doc
reference is intentionally left untouched).
- Not tested: Did not run a live `pip install headroom-ai` against PyPI
in CI.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

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

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-22 19:25:00 -05:00

2.9 KiB

Raw Blame History

Getting Started with Headroom

This guide will help you get up and running with Headroom in under 5 minutes.

Installation

Python:

# Core package (minimal dependencies)
pip install headroom-ai

# With proxy server
pip install headroom-ai[proxy]

# With semantic relevance (for smarter compression)
pip install headroom-ai[relevance]

# Everything
pip install headroom-ai[all]

TypeScript / Node.js:

npm install headroom-ai

Docker-native:

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

PowerShell:

irm https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.ps1 | iex

See Docker-native install for wrapper behavior, compose usage, and host-integrated wrap flows.

If you want Headroom to stay up in the background and automatically serve supported tools, use Persistent Installs:

headroom install apply --preset persistent-service --providers auto

Quick Start: Proxy Mode (Recommended)

The easiest way to use Headroom is as a proxy server:

# Start the proxy
headroom proxy --port 8787

Then point your LLM client at it:

# 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

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

That's it! All your requests now go through Headroom and get optimized automatically.

Quick Start: Python SDK

If you want programmatic control:

from headroom import HeadroomClient
from openai import OpenAI

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

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

Modes

Audit Mode

Observe without modifying:

client = HeadroomClient(
    original_client=OpenAI(),
    default_mode="audit",
)
# Logs metrics but doesn't change requests

Optimize Mode

Apply transforms to reduce tokens:

client = HeadroomClient(
    original_client=OpenAI(),
    default_mode="optimize",
)
# Compresses tool outputs, aligns cache prefixes, etc.

Simulate Mode

Preview what optimizations would do:

plan = client.chat.completions.simulate(
    model="gpt-4o",
    messages=[...],
)
print(f"Would save {plan.tokens_saved} tokens")
print(f"Transforms: {plan.transforms_applied}")

Next Steps

Proxy Server Documentation - Configure the proxy
Transforms Reference - Understand each transform
API Reference - Full API documentation

2.9 KiB Raw Blame History