Headroom：AI 代理的上下文压缩层
在到达 LLM 之前压缩工具输出、日志、文件和 RAG 分块，为编码代理节省 15-20% 的标记，为 JSON 节省 60-95%，同时不影响答案质量。
- Star 数
- ★ 76k
- 最近更新
- 1 天前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 59/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code · OpenAI API · Claude API
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 在日常开发中使用 Claude Code 或 Cursor 的编码员，希望减少 15-20% 的上下文标记，而不改变答案质量。
- 不适合
- 只用单一厂商原生压缩、不需要跨代理共享记忆的团队
- 无法在本地运行进程的沙箱环境
- 只做短对话或处理已高度密集文本、看不到明显压缩收益的用户
- 源码审查
- 59/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Headroom 是一个本地优先的上下文压缩层，用于 AI 代理，减少发送到 LLM 的标记数量，而不改变答案。它提供 Python 和 TypeScript 库、零代码代理、MCP 服务器以及跨代理共享内存。核心管道使用 ContentRouter 检测内容类型，然后使用 SmartCrusher 处理 JSON，基于 AST 的 CodeCompressor 处理代码，以及 Kompress-v2-base 模型处理文本。压缩是可逆的，通过 CCR 机制缓存原始内容，LLM 可按需检索。该项目支持通过代理与 Claude Code、Codex、Copilot、Cursor 等编码代理集成，并可透明地处理 Anthropic 和 OpenAI 兼容的 API。它还提供 headroom learn 工具，用于从失败会话中挖掘经验并写入 CLAUDE.md 等文件。
Headroom 在内容到达 LLM 之前运行多种操作。作为库，它提供了 compress() 函数，可直接处理消息。作为代理，它验证了 headroom proxy --port 8787 可为任何客户端提供一个兼容的代理。作为包装器，headroom wrap claude 启动一个本地代理，安装语义代码导航工具（如 Serena），并配置编码代理以路由流经 Headroom。它使用 ContentRouter 对输入进行分类，然后使用 SmartCrusher（JSON）、CodeCompressor（AST）或 Kompress-v2-base（文本）进行压缩。输出端的优化包括在需要时生成简洁的提示和减少推理努力的机制，由 HEADROOM_OUTPUT_SHAPER 控制。它启动一个 MCP 服务器，提供 headroom_compress、headroom_retrieve 和 headroom_stats 工具。它通过 headroom learn 从失败会话中挖掘经验，并将纠正记入 CLAUDE.md、AGENTS.md 或 GEMINI.md。
- 在日常开发中使用 Claude Code 或 Cursor 的编码员，希望减少 15-20% 的上下文标记，而不改变答案质量。
- 处理包含大量 JSON 数据的 SRE 或数据分析师，利用 SmartCrusher 实现 60-95% 的压缩。
- 负责 RAG 流程的开发者，希望在将大块文档发送给 LLM 之前压缩它们。
- 同时管理多个代理（如 Claude、Codex、Gemini）的工程师，希望通过跨代理内存实现共享上下文。
- 在 CI 环境中运行代理的团队，希望在此类工作负载上节省成本。
- 希望透明地与 Anthropic 或 OpenAI API 集成的开发者，通过 API 客户端适配器或代理。
如何安装或部署这个 Agent？
Headroom 可通过 pip 或 uv 安装为 Python 工具，并提供类型脚本 SDK。Python CLI 提供所有功能，TypeScript SDK 仅提供库功能。
如何使用这个 Agent？
安装后，您可以以不同模式运行 Headroom。 headroom proxy --port 8787 启动一个零代码代理。 headroom wrap claude 包装编码代理。 headroom deploy 提供一键部署。 headroom doctor 验证设置。
这个 Agent 有哪些优点和局限？
- 本地优先且可逆：数据保留在机器上，通过 CCR 恢复原始内容。
- 内容感知压缩：为 JSON、代码和文本使用专门的压缩器（SmartCrusher、CodeCompressor、Kompress-v2-base）。
- 与流行代理无关：支持 Claude Code、Codex、Copilot、Cursor 等，通过代理模式提供 OpenAI 兼容。
- 输出端优化：减少模型写回的标记，包括说服力的语气引导和思考预算的减少。
- 跨代理共享内存：跨多个代理上下文共享，自动去重。
- 设置复杂性：包装代理时需要本地代理和配置，可能需要调试。
- Python 版本要求：对 Python 3.13+ 有需求，LiteLLM 需要 Python 3.13。
- 性能损失：压缩过程增加延迟。
- X86 平台需要 AVX2：一些没有 AVX2 的旧 CPU 无法获得节省收益，依赖 ONNX Runtime。
- 与托管压缩服务相比，提供分层功能需要额外设置。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Headroom：AI 代理的上下文压缩层 当前 | 59 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 76k | 1 天前 | Python | Codex · Claude Code · OpenAI API · Claude API |
| AOCI-CODE：给编码智能体的代码库认知索引 | 52 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 1.6k | 4 天前 | Go | Codex · Claude Code |
| Loop Engineering | 69 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 12k | 今天 | TypeScript | Codex · Claude Code |
| Best of Agent Harnesses | 75 · 表现良好 | MCP 服务器免费 + 模型费 | ★ 1.3k | 今天 | Python | Claude Code · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：代理以本地优先运行，数据留在本机；有passthrough模式，敏感内容默认不处理；有安全策略文档，说明不存储API密钥；依赖有CVE修复和约束。扣分：未明确最小权限原则，代理可能以用户权限运行；用户确认机制不明确，wrap操作可能自动修改配置；外部影响（如修改用户配置文件）未充分说明；发布者身份未验证，来源归属不明确。
证据显示：README和pyproject.toml描述一致，功能列表清晰；依赖有版本约束和CVE修复；有CI测试和错误处理说明。扣分：未提供失败消息的具体示例，依赖可用性未完全验证（如模型下载依赖外部服务）。
证据显示：明确目标用户（开发者、团队），提供多种使用场景（库、代理、MCP）；能力边界清晰（支持多种代理和框架）；触发条件明确（wrap、proxy等命令）；环境适配良好（支持Python 3.10+，多种操作系统）。扣分：未详细说明所有环境限制（如Windows支持有限）。
证据显示：信息架构清晰，有文档、llms.txt；安装说明详细；命名稳定（headroom-ai）；有示例和FAQ；已知限制部分提及（如sandbox环境）；许可证为Apache-2.0；有版本号和changelog；维护责任有说明（社区支持）。扣分：发布者身份未验证，维护责任不明确。
证据显示：输出可用性高（压缩后仍可检索原始内容）；边际价值明确（节省token）；成本效益有数据支持（节省百分比）。扣分：未提供独立验证，成本效益数据可能来自内部测试。
证据显示：README中的性能数据有基准测试和复现命令；有多个来源（README、pyproject、CI）相互印证；事实和推断区分清晰（如输出节省是估计值）。扣分：跨来源验证有限，未提供第三方独立验证。
- 代理会修改用户配置文件（如CLAUDE.local.md），请确保备份或了解撤销方法。
- 依赖外部模型下载（如HuggingFace），在离线或受限网络环境中可能无法正常工作。
- 发布者身份未验证，请谨慎使用，并检查代码和依赖的安全性。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v0.41.0 Release v0.41.0
发布说明摘录
[0.41.0](https://github.com/headroomlabs-ai/headroom/compare/v0.40.0...v0.41.0) (2026-10-13) Features * antigravity: add native Google Antigravity IDE integration ([#3817](https://github.com/headroomlabs-ai/headroom/issues/3817)) ([cd4367b](https://github.com/headroomlabs-ai/headroom/commit/cd4367b040bf80b7358f100da54994f6d5fbfcfe)) * opencode: support the OpenCode 2.x plugin API ([#3999](https://github.com/headroomlabs-ai/headroom/issues/3999)) ([1d4b357](https://github.com/headroomlabs-ai/headroom/commit/1d4b357ca745549382e1ed9a3a6d39b5df52d3d5)) …在 GitHub 查看 ↗ -
v0.40.0 Release v0.40.0
发布说明摘录
[0.40.0](https://github.com/headroomlabs-ai/headroom/compare/v0.39.1...v0.40.0) (2026-10-06) ⚠ BREAKING CHANGES * proxy: read HEADROOM_LICENSE and make usage reporting opt-in ([#3857](https://github.com/headroomlabs-ai/headroom/issues/3857)) * drop the crewai extra to remove chromadb from the lockfile ([#3870](https://github.com/headroomlabs-ai/headroom/issues/3870)) Features …在 GitHub 查看 ↗ -
v0.39.1 Release v0.39.1
发布说明摘录
[0.39.1](https://github.com/headroomlabs-ai/headroom/compare/v0.39.0...v0.39.1) (2026-09-26) Bug Fixes * proxy: stop the 0.39.0 TPM limiter from refusing large-context requests forever ([#3806](https://github.com/headroomlabs-ai/headroom/issues/3806)) ([7968122](https://github.com/headroomlabs-ai/headroom/commit/7968122658c31c06ef3e5b1fe7911c8cb0a79ade))在 GitHub 查看 ↗