headroomlabs-ai/headroom

Headroom can route Copilot CLI subscription traffic through the local proxy:

headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o

The wrapper exchanges Headroom's reusable GitHub OAuth token for Copilot's short-lived API token and prints the upstream endpoint as COPILOT_PROVIDER_API_URL=... at launch. headroom copilot-auth login stores a Headroom-specific Copilot OAuth token, rather than relying on generic GitHub or Copilot CLI tokens that can read account metadata but are still rejected by Copilot's token-exchange endpoint.

For GitHub Enterprise Server or a custom-domain Copilot deployment, set one of these before launching. If both are set, the URL wins:

export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com
export GITHUB_COPILOT_ENTERPRISE_URL=https://ghe.example.com

For GitHub.com Enterprise Cloud URLs such as github.com/enterprises/your-enterprise, set neither — Headroom uses GitHub's normal token-exchange endpoint and the Copilot API endpoint advertised for the signed-in account.

Platform support. macOS auth reuse through Copilot CLI Keychain storage and Windows device authentication are live-tested. Copilot CLI 1.0.81 does not expose its Windows login through the legacy Credential Manager schema Headroom reads, so run headroom copilot-auth login on Windows. Linux Secret Service / secret-tool reuse is implemented but not yet validated on a real desktop. In Docker and CI, pass an explicit GITHUB_COPILOT_TOKEN or GITHUB_COPILOT_GITHUB_TOKEN instead of relying on host keychain access.

Headroom overrides Copilot's API proxy endpoint, so the VS Code model picker stays authoritative. GPT-5.5, GPT-5.6 Luna/Sol/Terra, Claude Sonnet/Opus and other Copilot models keep their original model IDs while traffic passes through the local compression proxy. Headroom does not patch VS Code or change Codex settings.

headroom copilot-auth login
headroom wrap vscode

Keep the command running and use Copilot normally. The short-lived upstream Copilot token is held only in the proxy process. Full guide →

The official Claude Code extension embeds Claude Code and reads the same user settings as the CLI. Install the proxy extra, then run the wrapper from the project you will open in VS Code:

pip install "headroom-ai[proxy]"
headroom wrap vscode-claude
# Optional: persist Claude Code's client-owned 1M model selector
headroom wrap vscode-claude --1m

Reload the VS Code window on first run. Keep the wrapper terminal running while you use the Claude Code panel; the dashboard or proxy log printed at startup shows requests and savings. Your Anthropic authentication and selected model are preserved. Ctrl+C stops the proxy; headroom unwrap vscode-claude restores the settings that existed before setup.

With --1m, Headroom writes the resolved [1m] model selector to Claude Code's top-level user setting and restores the exact prior model on headroom unwrap vscode-claude or when setup runs again without --1m. Use headroom wrap vscode-claude --no-configure --1m to print the setting without writing files.

Claude Code and Anthropic own 1M model support and account eligibility. Local tests prove persisted settings and restoration, not a live entitled VS Code session or the resulting context window. Full guide →

• SmartCrusher — universal JSON: arrays of dicts, nested objects, mixed types. It keeps error items, values outside the normal statistical range, and first/last boundaries, selected from field-variance statistics rather than a keyword list.
• CodeCompressor — AST-aware for Python, JS/TS, Go, Rust, Java, C/C++, C#, PHP.
• Kompress-v2-base — our HuggingFace model, trained on agentic traces.
• Image compression — 40–90% reduction through a trained ML router.
• CacheAligner — flags volatile content that would bust a provider KV-cache prefix; never rewrites prompts.
• Live-zone compression — only new bytes are compressed (fresh tool output, the latest turn). The frozen prefix stays byte-identical, so the provider cache survives, and history is never dropped.
• CCR — reversible compression; the model retrieves originals on demand.
• Cross-agent memory — shared store with agent provenance and auto-dedup.
• SharedContext — compressed context passing across multi-agent workflows.
• headroom learn — plugin-based failure mining for Claude, Codex and Gemini.

One request lifecycle is shared by compress(), the SDKs and the proxy:

Setup → Pre-Start → Post-Start → Input Received → Input Cached → Input Routed → Input Compressed → Input Remembered → Pre-Send → Post-Send → Response Received

• Transforms do the work: CacheAligner → ContentRouter → SmartCrusher / CodeCompressor / Kompress-base, live-zone only. IntelligentContext and RollingWindow were retired in PR-B1.
• Pipeline extensions observe or customise lifecycle stages through on_pipeline_event(...).
• Compression hooks sit alongside the lifecycle as an additional extension seam.
• Proxy extensions are the integration seam for ASGI middleware, routes and startup policy.

Provider- and tool-specific behaviour lives under headroom/providers/, so core orchestration stays focused on lifecycle, sequencing and policy:

• CLI/tool slices — headroom/providers/claude, copilot, codex, grok, openclaw
• Provider runtime slices — headroom/providers/claude, gemini, with shared backend dispatch in headroom/providers/registry.py
• wrap.py, client.py, cli/proxy.py and proxy/server.py delegate env shaping, API target normalisation, backend selection and transport dispatch

Prefer uv tool install for the CLI so the command lives in an isolated app environment. On macOS, pass --python 3.13 if your default python3 is newer than the current wheel set:

brew install python@3.13  # if 3.13 is not already available
uv tool install --python 3.13 "headroom-ai[all]"
uv tool update-shell      # if ~/.local/bin is not on PATH
headroom --version

Codex and other MCP clients often cannot inherit an interactive shell PATH. Configure the absolute path returned by command -v headroom:

[mcp_servers.headroom]
command = "/Users/you/.local/bin/headroom"
args = ["mcp", "serve"]

command = "headroom" only works when the client starts with a PATH that already includes the uv tool directory.

With pipx, choose the interpreter explicitly:

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

Native wheels currently cover macOS Apple Silicon and Linux. On Intel macOS, use the Docker-native install until native wheel support lands.

CPU requirement (x86/x86_64). The ONNX-backed features — Magika content detection and embedding relevance — use a precompiled ONNX Runtime that needs AVX2. On x86 hosts without AVX2 (some Docker/QEMU setups, older cloud VMs) Headroom falls back to its non-ONNX paths — BM25 relevance, heuristic detection — rather than crashing. arm64 and Apple Silicon need no AVX2.

headroom update          # detects pip / pipx / uv tool and upgrades in place
headroom update --check  # report the latest release without upgrading
headroom update --pre    # include pre-releases

headroom update works out how Headroom was installed (pip/venv, pip --user, pipx, uv tool) and runs the matching upgrade on macOS, Linux and Windows. For git checkouts, editable installs, Docker images and externally-managed system Pythons (PEP 668) it prints the correct manual step instead of guessing.

The proxy also prints a one-line "update available" notice at startup. It checks PyPI at most once a day, in the background, and never blocks. Opt out with HEADROOM_UPDATE_CHECK=off; it is also skipped in --stateless mode and CI.

If pip install "headroom-ai[all]" fails with CERTIFICATE_VERIFY_FAILED (unable to get local issuer certificate), your network runs SSL inspection — a MITM proxy presenting a company CA. The build backend (maturin) downloads rustup over a connection your TLS stack does not trust. Install Rust first so the build never fetches it:

# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable
# Windows
winget install Rustlang.Rustup && rustup default stable

Restart your shell, then install. A prebuilt wheel avoids the Rust build entirely: pip install --only-binary headroom-ai headroom-ai. Wheels are published for Windows (win_amd64), Linux (x86_64 / aarch64) and macOS (Apple Silicon and Intel), so those platforms never need a local Rust toolchain — the Rust-first step above is only for the sdist fallback when no wheel matches.

At runtime Headroom verifies upstream TLS against the operating system's certificate store — where IT installs the Zscaler / Netskope / Palo Alto root — plus certifi's public roots, so a managed machine normally needs no setup. headroom doctor --network shows who signed each upstream certificate, whether Headroom trusts it, and whether a gateway block page is in the way. If the root is not in the OS store, export it as PEM and set HEADROOM_CA_BUNDLE=/path/to/root.pem (NODE_EXTRA_CA_CERTS also works). Full guide and the domain list for IT: Corporate networks.

Two download hosts can still need attention:

• cdn.pyke.io — the ONNX Runtime for the Rust core, fetched with Mozilla's roots only. Pre-provide it with ORT_STRATEGY=system and ORT_LIB_LOCATION=/path/to/onnxruntime.
• huggingface.co — the kompress-base model (Python, OS store) and the Rust core's embedding model (Mozilla's roots only). If the domain is blocked, pre-download and run with HF_HUB_OFFLINE=1, or point HF_ENDPOINT at a trusted mirror.

Running with compression disabled (pure gateway) needs neither asset.

Intel macOS: no prebuilt ONNX Runtime (#941). ort-sys ships no prebuilt binary for x86_64-apple-darwin, so a source build fails by default even outside a corporate proxy. Point it at a system runtime:

brew install onnxruntime
ORT_STRATEGY=system \
ORT_LIB_LOCATION="$(brew --prefix onnxruntime)/lib" \
ORT_PREFER_DYNAMIC_LINK=1 \
  pip install "headroom-ai[all]"

# ORT is dlopen'd at runtime too:
export ORT_DYLIB_PATH="$(brew --prefix onnxruntime)/lib/libonnxruntime.dylib"

ORT_LIB_LOCATION must point at lib/, not the bare prefix, and ORT_PREFER_DYNAMIC_LINK=1 is required — without it ORT_STRATEGY=system still attempts static linking, which the Homebrew keg does not provide.

"Basic Constraints of CA cert not marked critical" only occurs with HEADROOM_CERT_STORE=bundled (the OS store verifies these roots fine). If TLS fails with:

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
Basic Constraints of CA cert not marked critical

then the corporate CA is found and trusted, and adding it to a CA bundle changes nothing. Python 3.13 with OpenSSL 3.x enables VERIFY_X509_STRICT by default, which enforces RFC 5280 §4.2.1.9: a CA cert's basicConstraints must be marked critical. Inspection roots such as Zscaler set CA:TRUE without the critical bit, so the chain is rejected.

HEADROOM_TLS_STRICT=0 clears only the strict flag, from every TLS context Headroom controls — the proxy's httpx upstream client and the urllib3/huggingface_hub path used for model downloads. Chain validation, signature, expiry and hostname checks all stay on.

HEADROOM_TLS_STRICT=0 headroom proxy --port 8787

The Rust core's downloads use rustls with Mozilla's roots and are unaffected by HEADROOM_TLS_STRICT and the CA variables; pre-provision ONNX Runtime with ORT_STRATEGY=system and models via HF_ENDPOINT as above.