Headroom

Headroom 简介

Headroom 是一款运行在本地终端的 AI 编程助手上下文压缩工具，核心理念是「让 AI 看到更少、回答一样好」。它能够将代码日志、工具输出、文件内容和 RAG 检索结果压缩至原来的 20%~40%，同时保持对 LLM 的回答质量。对于频繁使用 AI 编程助手的开发者而言，这意味着更低的 token 消耗、更少的上下文溢出和更流畅的编码体验。

核心能力

多模态压缩引擎：Headroom 内置三种专用压缩器——SmartCrusher 负责 JSON 结构数据（可压缩 60%~95%）、CodeCompressor 基于 AST 分析源码文件、Kompress-v2-base 处理自然语言文本。三者协同工作，自动识别内容类型并选择最优压缩路径。

可逆压缩（CCR）：所有原始内容在压缩前会缓存到本地，LLM 在需要时可随时通过检索工具恢复原始数据，确保信息不丢失。

跨 Agent 记忆共享：一次压缩后，同一本地存储可被 Claude Code、Codex、Gemini 和 Grok 等多种编程助手共享读取，避免重复压缩同一条内容。

headroom learn 智能学习：工具会挖掘历史上失败的会话记录，自动生成修正指令写入 CLAUDE.local.md、CLAUDE.md 或 AGENTS.md 等文件，实现跨会话的自我改进。

输出 Token 缩减：Headroom 不仅压缩输入，还能在模型输出侧进行精简，移除冗余格式和重复表述。

全平台 Agent 包装：一行命令即可为 Claude、Codex、Grok、Copilot、Cursor、Aider、Opencode、CLINE、Continue、Goose、OpenClaw、Vibe、Omp 和 Zcode 等 14 种主流编程助手启用压缩：

headroom wrap claude   # 启用 Claude 压缩
headroom unwrap .       # 恢复原始状态

MCP 服务器模式：提供 headroom_compress、headroom_retrieve 和 headroom_stats 三个 MCP 工具，任何 MCP 客户端均可接入使用。

安装配置

方式一：npm 全局安装（推荐）

npm install -g headroom-ai

方式二：Python 库安装

pip install headroom-ai

方式三：代理模式（无需修改代码）

headroom proxy --port 8787

启动后配置代理地址为 localhost:8787，即可对任意应用生效。

使用步骤

第一步：安装 Headroom 选择上述任一方式完成安装。

第二步：启用目标 Agent 的压缩

headroom wrap claude    # 为 Claude Code 启用压缩
headroom wrap cursor     # 为 Cursor 启用压缩

第三步：正常使用 AI 编程助手 压缩在后台静默运行，无需改变工作流程。所有发送给 LLM 的内容都会经过压缩管线。

第四步：查看压缩统计

headroom stats

查看当前会话的 Token 节省比例和各类内容的压缩率。

第五步（可选）：启用智能学习

headroom learn

让工具自动分析失败会话并写入改进建议文件。

适用场景

场景一：长上下文项目中的 Token 成本控制 当项目代码库超过数万行时，AI 助手每次检索都会产生大量上下文。Headroom 可将一次文件读取的 Token 消耗从数万压缩至数千。

场景二：RAG 检索结果压缩 RAG 系统向 LLM 提交的检索片段往往冗长重复，Headroom 的 SmartCrusher 可在保留核心语义的前提下大幅精简。

场景三：JSON API 响应精简 处理第三方 API 返回的大型 JSON 响应时，压缩效果最为显著，可达 60%~95%。

场景四：团队统一 AI 编程规范 通过 headroom learn 将团队积累的编码规范和常见修正写入共享文件，确保所有成员使用 AI 助手时输出一致。

适用人群

日均 AI 编程会话超过 2 小时、关注 Token 成本、需要管理大型代码库、或希望 AI 编程助手输出更精准的开发者。

工作原理

Headroom 的压缩管线由四个核心模块组成。ContentRouter 负责识别输入内容类型（JSON/代码/文本），并将内容分发至对应压缩器。SmartCrusher 针对 JSON 结构使用语义压缩算法，移除冗余字段同时保留关键数据；CodeCompressor 将代码解析为 AST，仅保留定义节点和关键逻辑行；Kompress-v2-base 对自然语言使用 HF 压缩模型，在本地完成文本精简。CacheAligner 标记会导致 KV 缓存失效的易失内容，确保压缩后的检索仍能准确定位原文。所有原始数据存储在本地 ~/.headroom/cache/ 目录，LLM 需要时可随时检索恢复。

官方链接

GitHub 仓库：https://github.com/chopratejas/headroom

官方文档：https://headroom.ai