██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗ ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║ ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║ ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║ ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ 面向 AI 代理的上下文压缩层

Token 减少 60–95% · 库 · 代理 · MCP · 内容感知压缩器 · 本地优先 · 可逆

文档 · 安装 · 验证 · 代理 · Discord · llms.txt

AI 代理 / LLM： 可阅读此处的 /llms.txt，或获取 实时索引 / 完整文档 blob。

---

Headroom 可在 AI 代理读取数据前对工具输出、日志、RAG 块、文件和对话历史进行压缩。同样的回答，只需极少量的 Token。

实时演示：10,144 → 1,260 tokens — 相同的 FATAL 仍被找到。

• 库 — 在 Python 或 TypeScript 中调用 compress(messages)，可嵌入任意应用
• 代理 — headroom proxy --port 8787，无需改动代码，适用于任意语言
• 代理包裹 — 一条命令 headroom wrap claude|codex|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe；用 headroom unwrap <工具> 撤销
• MCP 服务器 — 为任意 MCP 客户端提供 headroom_compress、headroom_retrieve、headroom_stats
• 跨代理记忆 — 跨 Claude、Codex、Gemini 的共享存储，自动去重
• headroom learn — 挖掘失败会话，将修正写入 CLAUDE.local.md（默认，已 gitignore）或 CLAUDE.md / AGENTS.md / GEMINI.md
• 输出 Token 缩减 — 裁剪模型写回的内容（不仅是你发送的），去除客套/重复代码并跳过低价值步骤上的深层“思考”。参见输出 Token 缩减
• 可逆（CCR） — 原始内容本地缓存，可按需检索

工作原理（30 秒）

 你的代理 / 应用
   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, 你自己的代码…)
        │   提示 · 工具输出 · 日志 · RAG 结果 · 文件
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Headroom   （本地运行 — 数据不离开你）             │
    │  ────────────────────────────────────────────────  │
    │  CacheAligner  →  ContentRouter  →  CCR            │
    │                    ├─ SmartCrusher   (JSON)        │
    │                    ├─ CodeCompressor (AST)         │
    │                    └─ Kompress-v2-base (文本, HF)  │
    │                                                    │
    │  跨代理记忆  ·  headroom learn  ·  MCP              │
    └────────────────────────────────────────────────────┘
        │   压缩后的提示  +  检索工具
        ▼
  LLM 服务商  (Anthropic · OpenAI · Bedrock · …)

• ContentRouter — 检测内容类型，选择最合适的压缩器
• SmartCrusher / CodeCompressor / Kompress-v2-base — 分别压缩 JSON、AST 或自然语言
• CacheAligner — 稳定前缀结构，提升服务商 KV 缓存的命中率
• CCR — 原始内容本地存储；LLM 需要时可调用 headroom_retrieve 取回

→ 架构 · CCR 可逆压缩 · Kompress-v2-base 模型卡

1 — 安装

pip install "headroom-ai[all]" # Python — 提供 headroom CLI npm install headroom-ai # 仅 TypeScript SDK — 不提供 headroom CLI

2 — 选择运行模式 (以下 headroom 命令来自 pip 安装的包)

headroom wrap claude # 包裹一个编程代理 headroom proxy --port 8787 # 零代码即插即用代理

或: from headroom import compress # 内联库调用

3 — 验证安装并查看节省效果

headroom doctor # 健康检查 — 确认路由正常工作 headroom perf headroom dashboard # 实时节省看板（需代理运行中）

headroom CLI 仅通过 PyPI 包发布。npm 的 headroom-ai 是 TypeScript SDK —— 一个通过 import { compress } from 'headroom-ai' 导入的库，不是 CLI，因此不提供 headroom 命令。

细粒度的 extras：[proxy]、[mcp]、[ml]、[code]、[memory]、[vector]（可选 HNSW 后端——需要 C++ 工具链，不包含在 [all] 中）、[relevance]、[image]、[agno]、[langchain]、[evals]、[pytorch-mps]（Apple GPU 上的 memory-embedder 卸载——设置 HEADROOM_EMBEDDER_RUNTIME=pytorch_mps）。需要 Python 3.10+。

真实代理工作负载的节省效果：

工作负载	压缩前	压缩后	节省率
代码搜索（100 条结果）	17,765	1,408	92%
SRE 事件调试	65,694	5,118	92%
GitHub Issue 分类	54,174	14,761	73%
代码库探索	78,502	41,254	47%

标准基准上的准确性保持：

基准	类别	N	Baseline	Headroom	Delta
GSM8K	数学	100	0.870	0.870	±0.000
TruthfulQA	事实性	100	0.530	0.560	+0.030
SQuAD v2	问答	100	—	97%	19% 压缩
BFCL	工具	100	—	97%	32% 压缩

复现命令：python -m headroom.evals suite --tier 1 · 完整基准测试与方法论

输出 Token 缩减（裁剪模型写回的 Token）

以上全部内容都在缩减你发送的提示。但你同样要为模型写回的每一个 Token 付费——在 Opus 级别的模型上，输出费用是输入的 5 倍。这些输出中有很多是浪费：“太好了，让我……”的开场白、重复你刚刚展示的代码，或者对读取文件等常规步骤进行不必要的深层“思考”。

Headroom 也可通过代理替你裁剪这些内容，无需修改任何代码：

• 详细度引导 — 在系统提示末尾追加一段简短的“保持简洁，不要复述上下文”指令（避免破坏提示缓存）。
• 思考努力路由 — 当某一轮仅是模型在获取到工具结果后继续执行时（如读取文件、测试通过），降低模型的思考深度。新问题和错误则保持完整的思考努力。

开启方式：

export HEADROOM_OUTPUT_SHAPER=1 # 默认关闭 headroom proxy --port 8787

已经在运行代理？ 这些开关在每次请求时会被实时读取，因此通过 headroom wrap 复用（而非启动）的代理无法看到你之后导出的环境变量——其环境变量在启动时已被快照。现在 headroom wrap 会通过环回 POST /admin/runtime-env 将你当前设置实时同步到运行中的代理，因此修改立即生效无需重启（无冷启动、无请求丢失、无缓存丢失）。请在执行 wrap 之前设置它们。在共享代理中这些覆盖是全局的——最后一次显式设置的值生效。

学习你期望的简洁程度。 人们不会口头上说他们要多简洁的回答——他们会通过行为表现出这一点（打断过长的回复，或在读完前就继续下一步）。headroom learn --verbosity 会读取你过往的会话并自动选择合适的程度：

headroom learn --verbosity # 预览发现的内容（试运行） headroom learn --verbosity --apply # 保存；代理此后将使用它

查看你节省了多少输出 Token。 输出节省是反事实的——我们永远看不到模型“本来会”写什么——因此 Headroom 报告的数值是带有置信区间的诚实估算，而非凭空捏造的数字：

headroom output-savings

缩减：31.7% (95% CI 27.7% … 35.7%) [估算]

想要一个实测数字而非估算？可以保留 10% 的会话不进行塑形作为对照组：export HEADROOM_OUTPUT_HOLDOUT=0.1。看板会在输入压缩卡片旁显示一张已节省输出 Token 卡片，标注 measured 或 estimated 及其置信区间。

→ 完整说明（含计量方法）：输出 Token 缩减

代理兼容性矩阵

代理	headroom wrap	备注
Claude Code	✅	--memory · --code-graph · --1m · --tool-search
Codex	✅	与 Claude 共享记忆
Cursor	手动设置	启动代理并打印适用于 Cursor 设置的 base URL
Aider	✅	启动代理 + 启动
Copilot CLI	✅	启动代理 + 启动
OpenClaw	✅	作为 ContextEngine 插件安装
OpenCode	✅	注入配置 · 启动代理 + 启动
Cline	✅	启动代理 + 注入配置
Continue	✅	启动代理 + 注入配置
Goose	✅	启动代理 + 启动
OpenHands	✅	启动代理 + 启动
Mistral Vibe	✅	启动代理 + 启动
Cortex Code	仅库模式	60–65% 节省（库模式；无 wrap）

任意兼容 OpenAI 的客户端都可通过 headroom proxy 工作。MCP 原生：headroom mcp install。撤销持久化包裹可用 headroom unwrap <工具>（支持：claude、copilot、codex、opencode、openclaw）。

GitHub Copilot CLI 订阅模式

Headroom 可将 GitHub Copilot CLI 订阅流量路由至本地代理：

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

这使 Headroom 能够拦截兼容 OpenAI 的 Copilot CLI 请求，并在转发到 GitHub Copilot 的托管 API 之前应用相同的代理压缩管道。包装器会将 Headroom 的可复用 GitHub OAuth Token 换取 Copilot 的短期 API Token，并在启动时输出形如 COPILOT_PROVIDER_API_URL=... 的上游端点。

headroom copilot-auth login 存储 Headroom 专用的 Copilot OAuth Token。这避免了依赖能够读取 Copilot 账户元数据但仍可能被 Copilot Token 交换端点拒绝的通用 GitHub 或 Copilot CLI Token。

对于 GitHub Enterprise Server 或自定义域名的 Copilot 部署，请在启动前设置部署域名：

export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com

对于类似 github.com/enterprises/your-enterprise 的 GitHub.com Enterprise Cloud URL，不要设置企业域覆盖。Headroom 会使用 GitHub 的常规 Token 交换端点以及为登录账户通告的 Copilot API 端点。

平台支持说明：通过 Copilot CLI Keychain 存储的 macOS 认证复用已进行过冒烟测试。Windows 凭据管理器、Linux Secret Service / secret-tool 以及 Docker/CI Token 注入路径已作为认证发现路径实现或规划中，但在被认为完全验证之前仍需进行真实操作系统验证。对于 Docker 和 CI，优先通过显式 GITHUB_COPILOT_TOKEN 或 GITHUB_COPILOT_GITHUB_TOKEN 传入，而不是依赖主机密钥链访问。

何时使用 · 何时跳过

非常适合的场景：

• 每天运行 AI 编程代理，并希望在不修改代码的情况下节省成本
• 跨多个代理工作，并希望共享记忆
• 需要可逆压缩——原始内容可检索

██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗ ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║ ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║ ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║ ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ The context compression layer for AI agents

60–95% fewer tokens · library · proxy · MCP · content-aware compressors · local-first · reversible

Docs · Install · Proof · Agents · Discord · llms.txt

AI agents / LLMs: read /llms.txt here, or fetch the live index / full docs blob.

---

Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens.

Live: 10,144 → 1,260 tokens — same FATAL found.

• Library — compress(messages) in Python or TypeScript, inline in any app
• Proxy — headroom proxy --port 8787, zero code changes, any language
• Agent wrap — headroom wrap claude|codex|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe in one command; undo with headroom unwrap <tool>
• MCP server — headroom_compress, headroom_retrieve, headroom_stats for any MCP client
• Cross-agent memory — shared store across Claude, Codex, Gemini, auto-dedup
• headroom learn — mines failed sessions, writes corrections to CLAUDE.local.md (default, gitignored) or CLAUDE.md / AGENTS.md / GEMINI.md
• Output token reduction — trims what the model writes back (not just what you send): drops ceremony/restated code and skips deep "thinking" on routine steps. See Output token reduction.
• Reversible (CCR) — originals are cached for retrieval on demand

How it works (30 seconds)

 Your agent / app
   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
        │   prompts · tool outputs · logs · RAG results · files
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Headroom   (runs locally — your data stays here)  │
    │  ────────────────────────────────────────────────  │
    │  CacheAligner  →  ContentRouter  →  CCR            │
    │                    ├─ SmartCrusher   (JSON)        │
    │                    ├─ CodeCompressor (AST)         │
    │                    └─ Kompress-v2-base (text, HF)  │
    │                                                    │
    │  Cross-agent memory  ·  headroom learn  ·  MCP     │
    └────────────────────────────────────────────────────┘
        │   compressed prompt  +  retrieval tool
        ▼
 LLM provider  (Anthropic · OpenAI · Bedrock · …)

• ContentRouter — detects content type, selects the right compressor
• SmartCrusher / CodeCompressor / Kompress-v2-base — compress JSON, AST, or prose
• CacheAligner — stabilizes prefixes so provider KV caches actually hit
• CCR — stores originals locally; LLM calls headroom_retrieve if it needs them

→ Architecture · CCR reversible compression · Kompress-v2-base model card

# 1 — Install
pip install "headroom-ai[all]"          # Python — ships the `headroom` CLI
npm install headroom-ai                 # TypeScript SDK only — no `headroom` CLI

# 2 — Pick your mode  (the `headroom` commands below come from the pip install)
headroom wrap claude                    # wrap a coding agent
headroom proxy --port 8787              # drop-in proxy, zero code changes
# or: from headroom import compress      # inline library

# 3 — Verify setup and see the savings
headroom doctor                         # health check — confirms routing is working
headroom perf
headroom dashboard                      # live savings dashboard (proxy must be running)

The headroom CLI ships only via the PyPI package. The npm headroom-ai is the TypeScript SDK — a library you import (import { compress } from 'headroom-ai'), not a CLI, so it provides no headroom command.

Granular extras: [proxy], [mcp], [ml], [code], [memory], [vector] (optional HNSW backend — needs a C++ toolchain, not in [all]), [relevance], [image], [agno], [langchain], [evals], [pytorch-mps] (Apple-GPU memory-embedder offload — set HEADROOM_EMBEDDER_RUNTIME=pytorch_mps). Requires Python 3.10+.

Savings on real agent workloads:

Workload	Before	After	Savings
Code search (100 results)	17,765	1,408	92%
SRE incident debugging	65,694	5,118	92%
GitHub issue triage	54,174	14,761	73%
Codebase exploration	78,502	41,254	47%

Accuracy preserved on standard benchmarks:

Benchmark	Category	N	Baseline	Headroom	Delta
GSM8K	Math	100	0.870	0.870	±0.000
TruthfulQA	Factual	100	0.530	0.560	+0.030
SQuAD v2	QA	100	—	97%	19% compression
BFCL	Tools	100	—	97%	32% compression

Reproduce: python -m headroom.evals suite --tier 1 · Full benchmarks & methodology

Output token reduction (cut what the model writes back)

Everything above shrinks the prompt you send. But you also pay for every token the model writes back — and on Opus-class models output costs 5× input. A lot of that output is waste: "Great, let me…" preambles, re-printing code you just showed it, and deep "thinking" on routine steps like reading a file.

Headroom can trim that too, from the proxy, without you changing any code:

• Verbosity steering — appends a short "be terse, don't restate context" note to the end of the system prompt (so your prompt cache still hits).
• Effort routing — when a turn is just the model resuming after a tool result (a file read, a passing test), it dials the model's thinking effort down. New questions and errors keep full effort.

Turn it on:

export HEADROOM_OUTPUT_SHAPER=1     # off by default
headroom proxy --port 8787

Already running a proxy? These switches are read live on every request, so a proxy that headroom wrap reused (rather than started) would not see a value you export afterwards — its environment was snapshotted at launch. headroom wrap now hot-syncs your current settings to the running proxy via a loopback POST /admin/runtime-env, so they take effect immediately with no restart (no cold start, no dropped requests, no lost caches). Set them before you wrap. On a shared proxy these overrides are global — the last explicit setting wins.

Learn the right terseness for you. People don't say how terse they want answers — they show it (they interrupt long replies, or move on before they could have read them). headroom learn --verbosity reads your past sessions and picks the level automatically:

headroom learn --verbosity            # preview what it found (dry run)
headroom learn --verbosity --apply    # save it; the proxy uses it from now on

See how many output tokens you saved. Output savings are counterfactual — we never see what the model would have written — so Headroom reports an honest estimate with a confidence range , never a made-up number:

headroom output-savings
# Reduction: 31.7%  (95% CI 27.7% … 35.7%)   [estimated]

Want a measured number instead of an estimate? Leave 10% of conversations unshaped as a control group: export HEADROOM_OUTPUT_HOLDOUT=0.1. The dashboard shows an Output Tokens Saved card next to input compression, labelled measured or estimated with the confidence band.

→ Full write-up incl. the measurement methodology: Output token reduction

Agent compatibility matrix

Agent	headroom wrap	Notes
Claude Code	✅	--memory · --code-graph · --1m · --tool-search
Codex	✅	shares memory with Claude
Cursor	Manual setup	starts proxy and prints base URLs for Cursor settings
Aider	✅	starts proxy + launches
Copilot CLI	✅	starts proxy + launches
OpenClaw	✅	installs as ContextEngine plugin
OpenCode	✅	injects config · starts proxy + launches
Cline	✅	starts proxy + injects config
Continue	✅	starts proxy + injects config
Goose	✅	starts proxy + launches
OpenHands	✅	starts proxy + launches
Mistral Vibe	✅	starts proxy + launches
Cortex Code	Library only	60–65% savings (library mode; no wrap)

Any OpenAI-compatible client works via headroom proxy. MCP-native: headroom mcp install. Undo durable wrapping with headroom unwrap <tool> (supports: claude, copilot, codex, opencode, openclaw).

GitHub Copilot CLI subscription mode

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

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

This lets Headroom intercept OpenAI-compatible Copilot CLI requests and apply the same proxy compression pipeline before forwarding to GitHub Copilot's hosted API. 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=... during launch.

headroom copilot-auth login stores a Headroom-specific Copilot OAuth token. This avoids relying on generic GitHub or Copilot CLI tokens that can read Copilot account metadata but may still be rejected by Copilot's token-exchange endpoint.

For GitHub Enterprise Server or custom-domain Copilot deployments, set the deployment domain before launching:

export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com

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

Platform support note: macOS auth reuse via Copilot CLI Keychain storage has been smoke-tested. Windows Credential Manager, Linux Secret Service / secret-tool, and Docker/CI token-injection paths are implemented or planned as auth-discovery paths, but still need real OS validation before they should be considered fully vetted. For Docker and CI, prefer passing an explicit GITHUB_COPILOT_TOKEN or GITHUB_COPILOT_GITHUB_TOKEN rather than relying on host keychain access.

When to use · When to skip

Great fit if you…

• run AI coding agents daily and want savings without changing your code
• work across multiple agents and want shared memory
• need reversible compression — originals are retrievable via CCR within the configured TTL

Skip it if you…

• only use a single provider's native compaction and don't need cross-agent memory
• work in a sandboxed environment where local processes can't run

Integrations — drop Headroom into any stack Your setup	Hook in with
Any Python app	compress(messages, model=…)
Any TypeScript app	await compress(messages, { model })
Anthropic / OpenAI SDK	withHeadroom(new Anthropic()) · withHeadroom(new OpenAI())
Vercel AI SDK	wrapLanguageModel({ model, middleware: headroomMiddleware() })
LiteLLM	litellm.callbacks = [HeadroomCallback()]
LangChain	HeadroomChatModel(your_llm)
Agno	HeadroomAgnoModel(your_model)
Strands	Strands guide
ASGI apps	app.add_middleware(CompressionMiddleware)
Multi-agent	SharedContext().put / .get
MCP clients	headroom mcp install
What's inside

• SmartCrusher — universal JSON: arrays of dicts, nested objects, mixed types.
• CodeCompressor — AST-aware for Python, JS/TS, Go, Rust, Java, C/C++, Perl.
• Kompress-v2-base — our HuggingFace model, trained on agentic traces.
• Image compression — 40–90% reduction via trained ML router.
• CacheAligner — stabilizes prefixes so Anthropic/OpenAI KV caches actually hit.
• CCR — reversible compression; LLM retrieves originals on demand.
• Cross-agent memory — shared store, agent provenance, auto-dedup.
• SharedContext — compressed context passing across multi-agent workflows.
• headroom learn — plugin-based failure mining for Claude, Codex, Gemini.

Pipeline internals

Headroom exposes one stable request lifecycle across compress(), the SDK, 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-v2-base.
• Pipeline extensions observe or customize lifecycle stages via on_pipeline_event(...).
• Compression hooks sit alongside the canonical lifecycle as an additional extension seam.
• Proxy extensions remain the server/app integration seam for ASGI middleware, routes, and startup policy.

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

• CLI/tool slices : headroom/providers/claude, copilot, codex, openclaw
• Provider runtime slices : headroom/providers/claude, gemini, plus shared backend/runtime dispatch in headroom/providers/registry.py
• Core files stay orchestration-first : wrap.py, client.py, cli/proxy.py, and proxy/server.py delegate provider-specific env shaping, API target normalization, backend selection, and transport dispatch.

Headroom OSS is built for individual developers : run headroom proxy or headroom wrap on your laptop and start cutting tokens in minutes — free, local-first, your data never leaves your machine.

Running it across a whole engineering org is a different job: a shared, always-on deployment; centralized config and version rollout; org-wide savings dashboards; SSO and access controls; air-gapped / VPC installs; and someone to call when it matters. That's what we help companies with — self-hosted with support, or fully managed.

If your team is spending real money on LLM tokens — Claude Code, Codex, Cursor, or agents running in CI — and you want those savings across everyone, not just one laptop:

→ Email hello@headroomlabs.ai with your stack and rough monthly LLM spend, and we'll help you roll Headroom out across your organization.

Everything in this repo stays open source (Apache 2.0). The managed offering is simply for teams that would rather have it deployed, supported, and scaled for them.

pip install "headroom-ai[all]"          # Python, everything — includes the `headroom` CLI
npm install headroom-ai                 # TypeScript SDK (library only — no `headroom` CLI)
docker pull ghcr.io/chopratejas/headroom:latest

Granular extras: [proxy], [mcp], [ml] (Kompress-v2-base), [code], [memory], [vector] (optional HNSW backend — needs a C++ toolchain, not in [all]), [relevance], [image], [agno], [langchain], [evals], [pytorch-mps] (Apple-GPU memory-embedder offload — set HEADROOM_EMBEDDER_RUNTIME=pytorch_mps). Requires Python 3.10+.

Note : [all] covers the core stack but excludes framework adapters. Install them separately: pip install "headroom-ai[langchain]" (also [agno], [strands], [anyllm], [bedrock]).

Using pipx? Choose a supported interpreter explicitly:

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

Pick 3.13 if you want dollar savings. The dashboard's Proxy $ Saved tile prices compression with LiteLLM, and LiteLLM can't be installed on Python 3.14+. On 3.14 token savings still track, but the dollar figure stays $0.00. If you already installed on 3.14, switch with pipx reinstall headroom-ai --python python3.13 and restart the proxy.

→ Installation guide — Docker tags, persistent service, PowerShell, devcontainers.

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 and older cloud VMs) Headroom automatically falls back to its non-ONNX paths (BM25 relevance, heuristic detection) rather than crashing. arm64/Apple Silicon needs 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 figures out how Headroom was installed (pip/venv, pip --user, pipx, uv tool) and runs the matching upgrade across 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 shows a one-line "update available" notice on startup. It checks PyPI at most once a day, in the background, and never blocks. Opt out with HEADROOM_UPDATE_CHECK=off (also skipped in --stateless mode and CI).

Corporate / SSL-inspection environments

If pip install "headroom-ai[all]" fails with CERTIFICATE_VERIFY_FAILED (unable to get local issuer certificate), your network uses SSL inspection — a MITM proxy presenting a company-issued CA. The build backend (maturin) downloads rustup over a connection your TLS stack doesn't trust. Install Rust first so the build doesn't fetch 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 pip install "headroom-ai[all]". A prebuilt wheel avoids the Rust build entirely where available: pip install --only-binary headroom-ai headroom-ai. Prebuilt wheels are published for Windows (win_amd64), Linux (x86_64 / aarch64), and macOS (Apple Silicon), so installs on those platforms never need a local Rust toolchain — the Rust-first dance above is only for the platform-independent sdist fallback (e.g. Intel macOS).

Two runtime assets are fetched over TLS; if they are blocked, trust your corporate CA via REQUESTS_CA_BUNDLE / SSL_CERT_FILE / CURL_CA_BUNDLE:

• cdn.pyke.io — the ONNX Runtime for the Rust core. Alternatively pre-provide it with ORT_STRATEGY=system and ORT_LIB_LOCATION=/path/to/onnxruntime.
• huggingface.co — the kompress-base compression model. Pre-download it and run with HF_HUB_OFFLINE=1, or set HF_ENDPOINT to a trusted mirror.

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

"Basic Constraints of CA cert not marked critical" (Python 3.13+ strict mode)

A different failure from the one above. 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 — adding it to a CA bundle changes nothing. Python 3.13 + OpenSSL 3.x enable VERIFY_X509_STRICT by default, which enforces RFC 5280 §4.2.1.9: a CA cert's basicConstraints must be marked critical. Inspection roots like Zscaler set CA:TRUE without the critical bit, so the chain is rejected.

Set HEADROOM_TLS_STRICT=0 to clear 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; this is strictly narrower than disabling verification.

HEADROOM_TLS_STRICT=0 headroom proxy --port 8787

The Rust core's ONNX download (cdn.pyke.io) uses a separate TLS stack (rustls / OS trust store), unaffected by HEADROOM_TLS_STRICT. On Windows the corporate root must be in the machine certificate store (browsers already trust it there); or pre-provision ONNX Runtime with ORT_STRATEGY=system + ORT_LIB_LOCATION=/path/to/onnxruntime to skip the download entirely.

headroom learn — mines failed sessions, writes corrections to CLAUDE.local.md (default, gitignored; use --target CLAUDE.md for the shared team file) / AGENTS.md / GEMINI.md.

Headroom runs locally , covers every content type, works with every major framework, and is reversible.

| Scope | Deploy | Local | Reversible
---|---|---|---|---
Headroom | All context — tools, RAG, logs, files, history | Proxy · library · middleware · MCP | Yes | Yes
RTK | CLI command outputs | CLI wrapper | Yes | No
lean-ctx | CLI commands, MCP tools, editor rules | CLI wrapper · MCP | Yes | No
Compresr, Token Co. | Text sent to their API | Hosted API call | No | No
OpenAI Compaction | Conversation history | Provider-native | No | No

Attribution. Headroom ships with the excellent RTK binary for shell-output rewriting — git show --short, scoped ls, summarized installers. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it. Headroom can also use lean-ctx as the selected CLI context tool; set HEADROOM_CONTEXT_TOOL=lean-ctx before running headroom wrap ....

git clone https://github.com/chopratejas/headroom.git && cd headroom
uv sync --extra dev && uv run pytest

Devcontainers in .devcontainer/ (default + memory-stack with Qdrant & Neo4j). See CONTRIBUTING.md.

Community

Apache 2.0 — see LICENSE.