headroom

Headroom 会在内容进入模型之前，压缩 AI Agent 读取的东西，包括工具输出、日志、RAG 片段、文件和对话历史。内容路由器会根据类型选择专门的压缩器（JSON、基于 AST 的源代码压缩，或用本地小模型压缩普通文本），原始内容缓存在本地，模型需要时可以取回全文。压缩在你的电脑上完成，内容不会被发送到任何地方。

凡是上下文大小影响成本或效果的场景，它都能派上用场：编程 Agent 读取冗长的日志和测试输出、Agent 调用返回大量 JSON 的 API，以及 RAG 流程。项目方给出的数据是：编程 Agent 场景约节省 20% 的 token，以 JSON 为主的内容可节省 60–95%。它可以作为 Python 或 TypeScript 库使用，也可以作为无需改代码的本地代理、MCP Server，或者用一条命令包装 Claude Code、Codex、Cursor、Aider 等 Agent。它还提供跨 Agent 的共享记忆，以及把失败会话总结成 CLAUDE.md、AGENTS.md 等文件中的说明的 `learn` 命令。

上手方式：用 `uv tool install --python 3.13 "headroom-ai[all]"` 或 pip 安装 CLI，然后运行 `headroom wrap claude`（或其他 Agent），或者 `headroom proxy --port 8787`。`headroom doctor` 用于检查配置，`headroom dashboard` 可以实时查看节省情况。