Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

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

JSON 数据 token 减少 60–95%，编程智能体 token 减少 15-20% · library · proxy · MCP · content-aware compressors · local-first · reversible

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

_{AI agents / LLMs: 请在此阅读 /llms.txt，或获取 实时索引 / 完整文档 blob。}

---

Headroom 会在数据到达 LLM 之前，压缩 AI 智能体读取的一切内容——工具输出、日志、RAG 分块、文件和对话历史。答案相同，token 仅为原来的一小部分。

_{实时：10,144 → 1,260 tokens — 同样发现了 FATAL。}

功能

• Library — 在 Python 或 TypeScript 中使用 compress(messages)，可内联嵌入任何应用
• Proxy — headroom proxy --port 8787，零代码改动，支持任何语言
• Agent wrap — 一条命令运行 headroom wrap claude|codex|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe；用 headroom unwrap <tool> 撤销
• MCP server — headroom_compress、headroom_retrieve、headroom_stats，适用于任何 MCP 客户端
• Cross-agent memory — 在 Claude、Codex、Gemini 之间共享存储，自动去重
• headroom learn — 挖掘失败会话，将修正写入 CLAUDE.local.md（默认，已 gitignore）或 CLAUDE.md / AGENTS.md / GEMINI.md
• Output token reduction — 精简模型写回的内容（不仅是发送内容）：去除套话/重复代码，并在常规步骤中跳过深度「思考」。参见 Output token reduction。
• Reversible (CCR) — 原文按需缓存，可供检索

工作原理（30 秒）

 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 — 检测内容类型，选择对应的压缩器
• SmartCrusher / CodeCompressor / Kompress-v2-base — 压缩 JSON、AST 或散文文本
• CacheAligner — 稳定前缀，使提供商 KV 缓存真正命中
• CCR — 本地存储原文；若需要，LLM 会调用 headroom_retrieve

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

快速开始（60 秒）

# 1 — Install
uv tool install "headroom-ai[all]"      # Install `headroom` CLI as a global tool in self-contained virtual env
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 uv or 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)

建议使用 headroom 时，每次启动一个包装后的智能体会话，以确保完成所有必要设置。包装编程智能体时，headroom 会启动本地代理，设置提供 rtk 和 tokensave 等工具的 MCP 服务器，并启动配置为将请求代理到 headroom 的编程智能体会话。

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 内存嵌入器卸载——设置 HEADROOM_EMBEDDER_RUNTIME=pytorch_mps）。需要 Python 3.10+。

Codex / 全局安装

如果 Codex 或其他 MCP 客户端无法可靠继承 shell 中的 PATH，请将 Headroom 安装为持久化的 uv 工具，并让客户端指向绝对二进制路径：

uv tool install "headroom-ai[all]"
command -v headroom

然后在 MCP 配置中使用返回的路径：

[mcp_servers.headroom]
command = "/absolute/path/from/command-v/headroom"
args = ["mcp", "serve"]

command = "headroom" 仅在客户端以已包含 uv 工具目录的 PATH 启动时有效。

验证

真实智能体工作负载上的节省：

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

标准基准测试中保持精度：

Benchmark	Category	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% compression
BFCL	工具	100	—	97%	32% compression

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

输出 token 削减（精简模型写回的内容）

上文所述都能缩小你发送的 prompt。但你也要为模型写回的每个 token 付费——而在 Opus 级模型上，输出成本是输入的 5 倍。其中大量输出是浪费："好的，让我…" 这类开场白、重复打印你刚展示给它的代码，以及在读取文件等常规步骤上的冗长 "思考"。

Headroom 也能从代理侧削减这些输出，无需你改动任何代码：

• 冗长度引导（Verbosity steering） — 在 system prompt 末尾追加一条简短的 "保持简洁，不要复述上下文" 说明（这样你的 prompt 缓存仍能命中）。
• 努力度路由（Effort routing） — 当某轮对话只是模型在工具结果之后继续（例如文件读取、测试通过），它会降低模型的思考努力度。新问题与错误仍保持全力。

开启方式：

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

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

找到适合你的简洁度。 人们不会说自己想要多简洁——他们会表现出来（打断冗长回复，或在读完之前就继续下一步）。headroom learn --verbosity 会读取你过往会话并自动选择级别：

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

查看你节省了多少输出 token。 输出节省是反事实的——我们永远看不到模型本来会写什么——因此 Headroom 报告的是诚实的估计值及置信区间，而不是编造数字：

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

想要实测数字而非估计值？将 10% 的对话留作未塑形对照组：export HEADROOM_OUTPUT_HOLDOUT=0.1。仪表板会在输入压缩旁显示 Output Tokens Saved 卡片，标注为 measured 或 estimated，并附带置信区间。

→ 完整说明（含测量方法学）：输出 token 削减

Agent 兼容性矩阵

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)

任何 OpenAI 兼容客户端均可通过 headroom proxy 使用。MCP 原生：headroom mcp install。 使用 headroom unwrap <tool> 撤销持久化包装（支持：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。这样可以避免依赖通用的 GitHub 或 Copilot CLI token——它们虽可读取 Copilot 账户元数据，但仍可能被 Copilot 的 token 兑换端点拒绝。

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

export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com

对于 github.com/enterprises/your-enterprise 这类 GitHub.com Enterprise Cloud URL，请勿设置 enterprise-domain 覆盖。Headroom 会使用 GitHub 的正常 token 兑换端点，以及为已登录账户公布的 Copilot API 端点。

平台支持说明：通过 Copilot CLI Keychain 存储在 macOS 上复用认证已通过冒烟测试。Windows Credential Manager、Linux Secret Service / secret-tool，以及 Docker/CI token 注入路径已实现或计划作为认证发现路径，但在被视为完全验证之前仍需要真实操作系统验证。对于 Docker 和 CI，建议显式传入 GITHUB_COPILOT_TOKEN 或 GITHUB_COPILOT_GITHUB_TOKEN，而不是依赖宿主机钥匙串访问。

何时使用 · 何时跳过

非常适合，如果你…

• 每天运行 AI 编程 agent，希望在不改代码的情况下节省成本
• 跨多个 agent 工作，并希望共享记忆
• 需要可逆压缩——在配置的 TTL 内可通过 CCR 取回原文

可以跳过，如果你…

• 只使用单一提供商的原生压缩，且不需要跨 agent 记忆
• 在沙箱环境中工作，本地进程无法运行

集成 — 将 Headroom 接入任意技术栈

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 指南
ASGI apps	app.add_middleware(CompressionMiddleware)
Multi-agent	SharedContext().put / .get
MCP clients	headroom mcp install

内含功能

• SmartCrusher — 通用 JSON：字典数组、嵌套对象、混合类型。
• CodeCompressor — 面向 AST（抽象语法树）的压缩，支持 Python、JS/TS、Go、Rust、Java、C/C++、Perl。
• Kompress-v2-base — 我们的 HuggingFace 模型，在 agentic traces 上训练。
• 图像压缩 — 通过训练的 ML 路由器实现 40–90% 缩减。
• CacheAligner — 稳定前缀，使 Anthropic/OpenAI KV 缓存能够真正命中。
• Live-zone 压缩 — 仅压缩新增字节（新的工具输出、最新轮次）；冻结前缀保持字节级一致，避免破坏提供商缓存。历史记录永不丢弃。
• CCR — 可逆压缩；LLM 按需检索原始内容。
• 跨 Agent 记忆 — 共享存储、Agent 来源追踪、自动去重。
• SharedContext — 在多 Agent 工作流之间传递压缩上下文。
• headroom learn — 基于插件的失败挖掘，适用于 Claude、Codex、Gemini。

流水线内部机制

Headroom 在 compress()、SDK 和代理之间暴露统一的稳定请求生命周期：

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

• Transforms 负责实际工作：CacheAligner → ContentRouter → SmartCrusher / CodeCompressor / Kompress-base（仅 live-zone；IntelligentContext 和 RollingWindow 已在 PR-B1 中退役）。
• Pipeline extensions 通过 on_pipeline_event(...) 观察或自定义生命周期阶段。
• Compression hooks 与规范生命周期并列，作为额外的扩展接入点。
• Proxy extensions 仍是服务器/应用集成的接入点，用于 ASGI 中间件、路由和启动策略。

提供商和工具特定行为位于 headroom/providers/ 下，核心编排专注于生命周期、序列和策略。

• CLI/工具切片：headroom/providers/claude、copilot、codex、openclaw
• 提供商运行时切片：headroom/providers/claude、gemini，以及 headroom/providers/registry.py 中的共享后端/运行时调度
• 核心文件保持编排优先：wrap.py、client.py、cli/proxy.py 和 proxy/server.py 将提供商特定的环境塑造、API 目标规范化、后端选择和传输调度委托出去。

面向团队的 Headroom

Headroom OSS 面向个人开发者：在笔记本电脑上运行 headroom proxy 或 headroom wrap，几分钟内即可开始削减 token —— 免费、本地优先，数据不会离开你的机器。

在整个工程组织中运行则是另一回事：需要共享的、始终在线的部署；集中式配置与版本发布；组织范围的节省仪表板；SSO 和访问控制；气隙/VPC 安装；以及关键时刻有人可联系。这正是我们帮助企业解决的问题 —— 自托管加支持，或全托管。

如果你的团队在 LLM token 上花费真金白银 —— Claude Code、Codex、Cursor 或在 CI 中运行的 Agent —— 并且你希望所有人都能享受这些节省，而不仅仅是一台笔记本电脑：

→ 请发送邮件至 hello@headroomlabs.ai，附上你的技术栈和大概的月度 LLM 支出，我们将帮助你在整个组织中推广 Headroom。

本仓库中的一切均为开源（Apache 2.0）。托管服务仅面向希望由我们部署、支持和扩展的团队。

安装

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

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

注意：[all] 涵盖核心技术栈，但不包含框架适配器。请单独安装：pip install "headroom-ai[langchain]"（还有 [agno]、[strands]、[anyllm]、[bedrock]）。

使用 pipx？请显式选择受支持的解释器：

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

若想看到美元节省，请选择 3.13。 仪表板的 Proxy $ Saved 磁贴使用 LiteLLM, 为压缩定价，而 LiteLLM 无法在 Python 3.14+ 上安装。在 3.14 上仍可追踪 token 节省，但美元数字会保持 $0.00。如果你已在 3.14 上安装，请使用 pipx reinstall headroom-ai --python python3.13 切换并重启代理。

→ 安装指南 —— Docker 标签、持久化服务、PowerShell、devcontainers。

CPU 要求（x86/x86_64）： 基于 ONNX 的功能 —— Magika 内容检测和嵌入相关性 —— 使用预编译的 ONNX Runtime，需要 AVX2。在没有 AVX2 的 x86 主机上（部分 Docker/QEMU 环境和较旧的云 VM），Headroom 会自动回退到非 ONNX 路径（BM25 相关性、启发式检测），而不是崩溃。arm64/Apple Silicon 不需要 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 会判断 Headroom 的安装方式（pip/venv、pip --user、pipx、uv tool），并在 macOS、Linux 和 Windows 上运行匹配的升级。对于 git checkout、可编辑安装、Docker 镜像和外部管理的系统 Python（PEP 668），它会打印正确的手动步骤，而不是盲目猜测。

代理还会在启动时显示一行「有可用更新」提示。它最多每天检查一次 PyPI，在后台进行，从不阻塞。使用 HEADROOM_UPDATE_CHECK=off 可退出（在 --stateless 模式和 CI 中也会跳过）。

企业 / SSL 检查环境

如果 pip install "headroom-ai[all]" 因 CERTIFICATE_VERIFY_FAILED（unable to get local issuer certificate）失败，说明你的网络使用了 SSL 检查 —— 一个呈现公司颁发 CA 的 MITM 代理。构建后端（maturin）通过你的 TLS 栈不信任的连接下载 rustup。请先安装 Rust，这样构建过程就不会再去获取它：

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

重启 shell，然后运行 pip install "headroom-ai[all]"。在可用的情况下，预构建 wheel 可完全避免 Rust 构建：pip install --only-binary headroom-ai headroom-ai。预构建 wheel 已为 Windows（win_amd64）、Linux（x86_64 / aarch64）和 macOS（Apple Silicon 和 Intel）发布，因此这些平台的安装永远不需要本地 Rust 工具链 —— 上述先装 Rust 的流程仅适用于没有匹配 wheel 时的平台无关 sdist 回退。

有两个运行时资源通过 TLS 获取；如果被阻止，请通过 REQUESTS_CA_BUNDLE / SSL_CERT_FILE / CURL_CA_BUNDLE 信任你的企业 CA：

• cdn.pyke.io —— Rust 核心的 ONNX Runtime。也可使用 ORT_STRATEGY=system 和 ORT_LIB_LOCATION=/path/to/onnxruntime 预先提供。
• huggingface.co —— kompress-base 压缩模型。预先下载并使用 HF_HUB_OFFLINE=1 运行，或将 HF_ENDPOINT 设置为受信任的镜像。

在禁用压缩（纯网关）的情况下运行，两者都不需要。

「CA 证书的 Basic Constraints 未标记为 critical」（Python 3.13+ 严格模式）

这与上述失败不同。如果 TLS 失败并显示：

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

则说明企业 CA 已被找到并信任 —— 将其添加到 CA 捆绑包不会有任何改变。Python 3.13 + OpenSSL 3.x 默认启用 VERIFY_X509_STRICT，它强制执行 RFC 5280 §4.2.1.9：CA 证书的 basicConstraints 必须标记为 critical。Zscaler 等检查根证书将 CA:TRUE 设置时未带 critical 位，因此证书链被拒绝。

将 HEADROOM_TLS_STRICT=0 设置为仅清除 Headroom 所管控的每个 TLS 上下文中仅有的 strict 标志 — 包括代理的 httpx 上游客户端以及用于模型下载的 urllib3/huggingface_hub 路径。证书链校验、签名、过期与主机名校验均保持开启；这严格窄于禁用验证。

HEADROOM_TLS_STRICT=0 headroom proxy --port 8787

Rust 核心的 ONNX 下载（cdn.pyke.io）使用独立的 TLS 栈（rustls / 操作系统信任库），不受 HEADROOM_TLS_STRICT 影响。在 Windows 上，企业根证书必须位于计算机证书存储区（浏览器已在此信任该证书）；或使用 ORT_STRATEGY=system + ORT_LIB_LOCATION=/path/to/onnxruntime 预置 ONNX Runtime，以完全跳过下载。

headroom learn

headroom learn — 挖掘失败会话，将修正写入 CLAUDE.local.md（默认，gitignored；团队共享文件请使用 --target CLAUDE.md）/ AGENTS.md / GEMINI.md。

Documentation

从这里开始	深入了解
快速入门	架构
代理	压缩原理
MCP 工具	CCR — 可逆压缩
记忆	缓存优化
失败学习	基准测试
配置	限制
持久化安装 (headroom init / headroom install apply)	节省分析 (headroom savings / headroom perf / headroom doctor)

Compared to

Headroom 在本地运行，覆盖所有内容类型，兼容所有主流框架，且可逆。

	范围	部署	本地	可逆
Headroom	全部上下文 — 工具、RAG、日志、文件、历史	代理 · 库 · 中间件 · MCP	Yes	Yes
RTK	CLI 命令输出	CLI 包装器	Yes	No
lean-ctx	工具输出、文件、shell、历史	代理 · 库 · 中间件 · MCP · CLI	Yes	Yes
Compresr, Token Co.	发送至其 API 的文本	托管 API 调用	No	No
OpenAI Compaction	对话历史	提供商原生	No	No

致谢。 Headroom 内置了出色的 RTK 二进制文件，用于 shell 输出改写 — git show --short、作用域 ls、摘要化安装器。衷心感谢 RTK 团队；他们的工具是我们技术栈的一等公民，Headroom 会压缩其下游的一切内容。Headroom 也可将 lean-ctx 用作选定的 CLI 上下文工具；运行 headroom wrap ... 前请设置 HEADROOM_CONTEXT_TOOL=lean-ctx。

Contributing

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

位于 .devcontainer/ 中的 Devcontainers（默认 + 含 Qdrant 与 Neo4j 的 memory-stack）。请参阅 CONTRIBUTING.md。

Community

• Discord — 提问、反馈、实战经验。
• HuggingFace 上的 Kompress-v2-base — 我们文本压缩背后的模型。

License

Apache 2.0 — 参见 LICENSE。