最近在用Claude Code的时候发现一个问题——跑几个复杂任务下来，Token消耗快得吓人。尤其是那种需要读大量文件、搜索代码库的场景，一轮对话下来几万Token就没了。

后来找到了**Headroom**这个项目，试了一下确实有效果。

## 它是做什么的

简单说，Headroom是一个**上下文压缩层**。它在你的AI Agent和LLM之间加了一层，把要发送的内容先压缩一遍再送给模型。

核心卖点：
- **省Token**：官方数据是60-95%的削减
- **不影响准确率**：在GSM8K、TruthfulQA等基准测试上，压缩后准确率基本不变
- **本地运行**：数据不会上传到任何地方
- **可逆压缩**：原始内容保留着，模型需要的时候可以取回来

## 实际效果

官方给出的测试数据：

| 场景 | 压缩前 | 压缩后 | 节省 |
|------|--------|--------|------|
| 代码搜索（100条结果） | 17,765 tokens | 1,408 tokens | 92% |
| SRE故障排查 | 65,694 tokens | 5,118 tokens | 92% |
| GitHub Issue分类 | 54,174 tokens | 14,761 tokens | 73% |
| 代码库探索 | 78,502 tokens | 41,254 tokens | 47% |

我在自己项目里试了一下，大概能省50-70%左右，没有官方说的那么夸张，但确实能省不少。

## 怎么用

最简单的方式是一行命令包裹你的Agent：

```bash
# 安装
pip install "headroom-ai[all]"

# 包裹Claude Code
headroom wrap claude

# 包裹Codex
headroom wrap codex

# 或者用代理模式（零代码改动）
headroom proxy --port 8787
```

代理模式最方便——它启动一个本地代理服务器，你的Agent配置指向这个代理就行，不用改任何代码。

## 支持哪些Agent

| Agent | 支持方式 |
|-------|----------|
| Claude Code | `headroom wrap claude` |
| Codex | `headroom wrap codex` |
| Cursor | 打印配置，粘贴一次即可 |
| Aider | 启动代理+启动 |
| Copilot CLI | 启动代理+启动 |

基本上主流的编程AI助手都支持。

## 几个亮点

**1. 跨Agent记忆共享**

如果你同时用Claude Code和Codex，Headroom可以在它们之间共享压缩后的上下文，避免重复处理相同内容。

**2. `headroom learn`**

这个功能挺有意思——它会分析你失败的会话，找出问题所在，然后自动写入`CLAUDE.md`或`AGENTS.md`，相当于让Agent自己总结经验教训。

**3. 内容感知压缩**

不是简单的截断或删减，而是根据内容类型选择不同的压缩算法：
- JSON数据 → SmartCrusher
- 代码 → CodeCompressor（AST感知）
- 文本 → Kompress-base（专门训练的模型）

## 适合谁用

- 每天用AI编程助手，Token消耗大的开发者
- 同时用多个Agent，想要统一管理的团队
- 对数据隐私有要求，不想把代码发到外部服务的人

## 不适合谁用

- 只用单一Agent，且用量不大
- 沙箱环境，没法跑本地进程

---

项目地址：https://github.com/chopratejas/headroom

1.4万星，Apache 2.0协议，Python和TypeScript都支持。如果你也在为Token费用头疼，可以试试。