Headroom 是放在 Agent 与 LLM provider 之间的本地 context compression layer，压缩工具输出、日志、文件、RAG 片段和历史对话，减少重复 token。
来源：官方 Releases 查看 GitHub 仓库 → 📘 使用教程 →官方 README 给出四类 trace 的参考结果：代码搜索 21%、SRE 事故调试 57%、代码库探索 42%、GitHub issue triage 30%；这些数字明确是参考测量，适合用自己的 trace 复测。
来源：官方 Releases官方 README 提供 headroom wrap 入口，可在不改 Agent 代码的情况下包住 Claude Code、Codex 等客户端。
来源：github.com/headroomlabs-ai/headroom项目文档把 proxy、Python library 和 MCP server 作为独立集成方式，适合不同调用链。
来源：docs.headroomlabs.ai官方 CLI 提供 headroom perf，用代表性 trace 对比压缩前后的 token 和效果。
来源：github.com/headroomlabs-ai/headroom请求先经过 Headroom 的压缩/缓存层，再转发到模型；需要原文时可按引用取回。它可以作为 CLI wrapper、HTTP proxy、Python library 或 MCP server 使用。
来源：官方 ReleasesPython 3.10+（CLI）pip 或 Docker按集成方式准备 Agent/provider长上下文编码任务、重复日志/工具输出、RAG 或多轮 Agent trace；短而紧凑的文本不应预期高节省。
来源：官方 Releasesv0.37.0（2026-08-27，官方 release）。
来源：官方 Releasesstatus: official_docs_checked_not_locally_installed | checked_at: 2026-09-22 | environment: 核对官方仓库、README、docs 和 v0.37.0 release；当前工作区未跑真实 Agent trace | limitations: 未在本机复现节省比例；不能把官方四类 trace 的结果当作本网站所有任务的保证 | observed_output: 官方 proof table 列出 21/57/42/30 四项参考值，README 同时提供 headroom doctor、wrap 和 perf 命令
来源：官方 Releases相比直接给 Agent 增加更大的 context window，Headroom 通过压缩和引用回取降低输入重复；如果上下文短、重复少或不想维护 proxy，直接调用 provider 更简单。
来源：官方 Releases适合有长上下文和重复工具输出的 Agent 工作流；不要把 proof table 写成所有任务的固定收益。
来源：官方 ReleasesHeadroom 是一个本地的 AI Agent 上下文压缩层，由 headroomlabs-ai/headroom 开源（Apache-2.0）。它坐在 Agent 与 LLM 之间，把 Agent 读到的工具输出、日志、RAG chunk、文件、对话历史压缩之后再发给模型。官方 proof table 在四类固定场景中报告 21–57% 的节省；这不是所有工作负载的保证。压缩是可逆的（CCR），LLM 需要原文时可以按需取回。
三选一：pip install "headroom-ai[all]"（Python，3.10+）；npm install headroom-ai（TypeScript SDK，不提供 CLI）；或 docker pull ghcr.io/headroomlabs-ai/headroom:latest && docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest。
官方兼容矩阵覆盖 Claude Code、Codex、OpenCode、Copilot CLI、Cursor、Aider、Cline、Continue、Goose、OpenHands、OpenClaw 等。任何 OpenAI 兼容客户端也可以走 headroom proxy。
headroom wrap copilot --subscription -- --model gpt-4o——把 Copilot CLI 的 OpenAI 兼容请求经本地代理压缩后再转发到 GitHub 托管 Copilot API。
官方 proof table 的四类固定场景分别是代码搜索 21%、SRE 事故调试 57%、代码库探索 42%、GitHub issue triage 30%。官方 README 同时说明短对话、低重复和已经很紧凑的文本节省很少。建议跑 headroom perf 看你自己的 trace 实际效果。
压缩器、代理、MCP server、CCR 原文存储都在你的机器上跑。只有压缩后的 prompt 才会发给你配置的上游 LLM 提供商，所以提供商看到的请求与你直接调用它时一样（只是体积小很多）。
本教程覆盖安装与四种集成形态。架构、CCR 内部原理、Kompress-base 模型卡、各 provider 的细节请看官方源：github.com/headroomlabs-ai/headroom 与 docs.headroomlabs.ai。