项目简介
Headroom 是一个为 AI 智能体（AI Agent）打造的上下文压缩层。它在提示词、工具输出、日志、RAG 检索片段、文件和对话历史到达大模型之前进行压缩，让你在获得相同答案的同时， Token 成本大幅下降。官方实测：JSON 类数据可减少 60–95% 的 Token，编码类智能体可减少 15–20%。
核心功能
- 多种部署形态：Python/TypeScript 内联库、
headroom proxy零代码代理、headroom wrap一键包装 Claude/Codex/Cursor/Aider/Cline 等主流 Agent，以及原生 MCP Server。 - 内容感知压缩：
SmartCrusher专攻 JSON，CodeCompressor基于 AST 压缩代码，Kompress-v2-base用自研 HuggingFace 模型处理自然语言。 - 可逆压缩（CCR）：原始内容本地缓存，LLM 可通过
headroom_retrieve按需取回，绝不丢失信息。 - 跨 Agent 记忆：同一台机器上 Claude、Codex、Grok、Gemini 等工具可共享记忆库并自动去重。
- 输出 Token 优化：通过 Verbosity steering 和 Effort routing，自动削减模型废话、重复代码和过度思考，进一步降低输出侧成本。
- headroom learn：自动挖掘失败会话，把纠偏规则写入
CLAUDE.local.md、AGENTS.md或GEMINI.md，让 Agent 越用越聪明。
安装要求和过程
环境要求：Python 3.10+。推荐用 uv 或 pip 安装；TypeScript 开发者也可用 npm 安装 SDK（仅库，无 CLI）。
# 推荐：uv 全局工具安装（隔离环境） uv tool install --python 3.13 "headroom-ai[all]" # 或者 pip pip install "headroom-ai[all]" # TypeScript SDK（仅库） npm install headroom-ai
启动方式三选一：
# 一键部署 + 自动配置 Agent headroom deploy # 包装 Claude Code（自动启动本地代理并注入配置） headroom wrap claude # 零代码 drop-in 代理 headroom proxy --port 8787
验证：
headroom doctor # 健康检查 headroom perf # 性能报告 headroom dashboard # 实时节省看板
典型使用场景
场景 1：AI 编码助手降本增效
你每天用 Claude Code、Cursor 或 Codex 处理大型代码库。代码搜索结果、RAG 片段、测试日志动辄几万 Token。Headroom 自动压缩输入内容，代码搜索场景可减少 92% Token，而答案质量不变。配合 headroom learn，它还能把常见误操作自动写入项目本地规则文件。
场景 2：SRE 事故排查
排查线上事故时，需要把大量日志、监控输出、GitHub Issue、运行时报错塞进上下文。Headroom 对日志和结构化数据压缩率极高，65k Token 的排查材料可压缩到 5k 左右，让智能体在上下文窗口内“看完全部证据”，而不是被截断。
场景 3：多 Agent 共享记忆
你在同一项目里混用 Claude Code、Codex、Grok CLI 和 Aider。Headroom 提供跨 Agent 的共享记忆存储，避免每个工具重复读取文件、重复建立上下文，真正实现“一次理解，处处可用”。
推荐理由
Headroom 最让我喜欢的一点是“不绑架你的工作流”。它既可以是库，也可以是代理，还可以一键 wrap 你已有的 Agent，不需要重写 prompt 或迁移模型。而且它是本地优先的，原始内容不会离开你的机器，企业敏感代码也能放心使用。
更难得的是，它在省钱的同时还做了“可逆压缩”和“失败学习”：前者保证信息不丢，后者让 Agent 越用越准。对于已经在用 Claude Code、Cursor、Codex 等工具的开发者来说，Headroom 几乎是“装完就能省钱”的基础设施。
下载地址
- GitHub 仓库：https://github.com/headroomlabs-ai/headroom
- 官方文档：https://docs.headroomlabs.ai/docs
- PyPI：https://pypi.org/project/headroom-ai/
- HuggingFace 模型：Kompress-v2-base
Headroom 采用 Apache 2.0 协议开源，当前 Stars 约 63.2K，主要语言为 Python。
