老实说，

用过 Claude Code、Codex 这类 coding agent 的人。大概都有过盯着它烧 token 的经历。你让它排查一个线上问题，它先 grep 一遍代码。再 cat 几个文件，跑一轮测试看输出，翻几屏日志，最终去 GitHub 上查相关 issue。这一连串动作里每一步的输出都会被原封不动塞回对话。成为接下来推理的上下文，而这些内容大多又长又重复，真正有用的可能就那么几行。一个任务还没跑完，token 就已经哗哗地流出去了。按理说，这些 token 你既要按输入计费为它们付钱。它们还会挤占本就有限的，

Headroom 介绍

Headroom 是一个面向 AI agent 的上下文压缩层。它的定位很直接：在一段内容进入大模型之前。先把它压缩一遍，在不改变语义的前提下把喂给模型的 token 数砍下来。

为什么需要上下文压缩？——使用者痛点

• 一次代码搜索命中上百处。每处还带出成片的源代码，可真正有用的往往只是函数签名和所在位置；大段函数体细节模型多半用不上。
• 线上事故日志动辄几万行，关键信息往往只有几段异常堆栈。不过，
• RAG 拉回来的文档片段之间常有大量冗余。
• 大 JSON 数组里几百个结构相同的元素，模型只需要几个样本即可。

如果把这些冗余全部塞进上下文。会产生两个后果：

1. 成本飙升：输入 token 越多，每次调用越贵，而一个任务可能要调用几十甚至上百次模型。
2. 上下文被挤占：有限的窗口被垃圾内容填满。真正关键的信息被稀释或直接被踢出，导致模型表现下降。

官方压缩基准

场景	压缩前 token	压缩后 token	节省率
代码搜索	-	-	%–%
SRE 事故排查	-	-	%–%
GitHub issue 分诊	-	-	%–%
代码库探索	-	-	%–%

压缩幅度与内容类型强相关：结构高度重复的工具输出能压掉九成以上；信息密度本来就高的代码库探索只能压掉不到一半，这也符合直觉——冗余越多越好压。

准确率保持甚至提高——评测结果展示

%% 压缩后略升 % % 压缩后略升 -

评测集	压缩前准确率 / 分数	压缩后准确率 / 分数	备注
GSM8K	0.870	0.870	-
TruthfulQA	+0.030提高	+0.030提高	-
SQuAD v2
BFCL % % 压缩后略升 % % 压缩后略升 -

从这组数字看，Headroom 在保住准确率甚至轻微提高的前提下把 token 大幅削减。去除无关冗余、让关键信息更突出，本来就能帮助模型更快聚焦主要。

主要特性

• 内容感知路由： Headroom 并非“一刀切”。而是先判断内容类型，再挑对应的压缩器。ContentRouter能够识别 JSON、源代码、纯文本、日志、diff 等类型，把每一段路由到最合适的压缩器上。混合内容会被拆分、分段路由再拼回去，从根本上避免因误删导致的信息缺失。不过，
• CCR 可逆压缩： 担心“关键细节被删掉”吗？Headroom 引入 CCR机制**。在压缩时同步缓存原始文本，并提供 headroom_retrieve 工具。让模型在需要更细粒度信息时主动调取缓存，在 TTL内实现“可逆”。这直接消除了“信息不可恢复”的恐慌。
• 跨 Agent 记忆： 很多团队同时使用 Claude、Codex、Gemini 等多个 agent，但它们之间互相隔离。Headroom 的 SharedContext 能在不同 agent 之间共享已压缩且去重后的上下文。并保留来源标注，让跨工具协作不再受限于单一对话窗口。
• 本地优先： 所有压缩、缓存与记忆均在本机完成，不会把代码、日志等敏感数据外发。按理说，内置文本压缩模型 chopratejas/kompress-v2-base<\/code> 运行于 Rust 主要层。遥测默认关闭，仅在手动设 HEADROOM_TELEMETRY=on<\/code> 时才开启。这对合规要求严格的团队尤为关键。话说回来，

四种使用方式

The package is published on PyPI under name headroom-ai<\/code>,Apache‑2.0 licensed,and requires Python >= 3.x. Although it’s a Python package,heavy‑lifting compression core is written in Rust and distributed as a pre‑compiled wheel via . No local Rust toolchain is needed.

Maturin packages Rust code into a standard Python wheel . It’s same toolchain used by popular projects like Pydantic‑core<\/code>,Pandas<\/code>。and LanceDB<\/code>.

A single pip command installs everything:

$ pip install "headroom-ai" # 包含代理、MCP 与可选模型等依赖

The following four integration patterns let you pick most convenient way for your workflow.

1️⃣ 当库用 – 手动调用 compress

from headroom import compress
# messages 必须是标准 Anthropic / OpenAI 消息格式
result = compress
print # 压缩后的消息列表
print # 节省的 token 数
print # 如 0.45 表示省了 55%

• The function works with any HTTP client .
• If compression would increase token count,it automatically falls back to original payload.

2️⃣ 当代理用 – 零改动拦截所有 LLM 调用

$ headroom proxy --port 8000 # 本地代理监听端口

You only need to point your client’s base URL to http://localhost:8000<\/code>. All requests pass through Headroom for transparent compression.

3️⃣ 包裹 Agent – 为现有 coding agent “穿上” Headroom 外衣

$ headroom wrap claude # 支持 Claude Code 系列
$ headroom wrap codex # 支持 Codex / Copilot 系列
$ headroom wrap cursor #…还有 Aider / Opencode / Continue 等众多工具

The command launches a local wrapper that automatically compresses every round‑trip 娱乐ween agent and its LLM backend. To revert:

$ headroom unwrap claude

4️⃣ 当 MCP Server 用 – 把 “取回原文” 能力暴露为标准工具接口

MCP is becoming lingua franca for agents that need external tools or data sources. Headroom can run as an MCP server so agents can invoke two built‑in tools:

• 'headroom_compress': 接收任意文本并返回已压缩版本。
• 'headroom_retrieve': 在需要细节时请求原始片段。\l\l\l\l\l\l\l\l \ \ \ \ \ \ \ \

秒上手预览 – 包裹 Agent 示例

The quickest way to feel Headroom’s effect is to use "wrap" mode.

$ head room wrap claude
\ n \ n \ n \ n \ n
\ n \ n \ n \ n

The command starts a local proxy that forwards Claude Code requests through HeadRoom before hitting real API—no code changes required.

To stop wrapping:

bash $ head room unwrap claude

If you use an unsupported tool。just launch a generic proxy:

bash $ head room proxy --port 8080

Then point any compatible client at http://localhost:8080. While running you can open a live dashboard:

bash $ head room dashboard

The dashboard shows real‑time statistics such as total tokens saved,compression ratio per request,and cache hit/miss rates.

定位的观点是，面向 AI agent 的上下文压 缩层，在进入大模型前先进行语义保持式降 Token；官方称能减少 % 到 % 而答案基本不变。

...

---