headroom （LLM 上下文压缩工具）
79,377
Stars
0
Forks
0
Watchers
0
Open Issues
未知
许可证
Python
语言
创建时间
最近更新
项目能做什么
在输入 LLM 前压缩工具输出、日志与 RAG 分块，大幅节省 Token 且不影响回答质量。
来源：AI 基于仓库事实生成
· 内容以仓库实际 README 为准
使用说明 查看原始 README 原仓库文档
项目简介
Headroom（在 PyPI 和 npm 上名为 headroom-ai）是一个专为 AI agent 打造的上下文压缩层。它可以在工具输出、日志、RAG 分块、文件和对话历史发送给 LLM 之前对其进行压缩，在保证回答质量不变的前提下减少输入 token 消耗。
根据官方实测数据，在四个 agent 场景下可减少 21–57% 的输入 token，在重复的 JSON 数组和日志行上可减少 90% 以上（纯散文内容压缩较少）。所有压缩操作均在本地机器运行，不会将任何 prompt 或文件内容发送到外部。
核心功能
- Library（代码库模式）：在 Python 或 TypeScript 中直接调用
compress(messages)，内联集成到应用中。 - Proxy（代理模式）：运行
headroom proxy --port 8787，无需修改代码即可适配任何编程语言。 - Agent wrap（一键包装）：一条命令即可接入主流编程 agent，支持
headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|droid|zcode；如需还原，执行headroom unwrap <tool>。 - MCP server：为任何 MCP 客户端提供
headroom_compress、headroom_retrieve、headroom_stats工具。 - Cross-agent memory：在 Claude、Codex、Gemini 和 Grok 之间共享存储，支持自动去重。
headroom learn：用于挖掘失败会话（具体细节因原文截断未完整展示，请查看原仓库）。
适合谁用
- LLM 应用开发者：使用 Python（如 LangChain、LiteLLM、Agno、Strands）或 TypeScript 开发 AI 应用的开发者。
- 编程 Agent 用户：日常使用 Claude Code、Codex、Cursor、Copilot、OpenCode、Aider 等工具的开发者。
安装步骤
1. Python 应用集成
pip install headroom-ai
使用示例：
from headroom import compress
# 传入 OpenAI 或 Anthropic 格式的 message 字典
result = compress(messages, model="gpt-4o")
client.chat.completions.create(model="gpt-4o", messages=result.messages)
2. TypeScript 应用集成
安装 npm 包，并同时安装和启动本地代理（npm SDK 会将消息发送至该代理）：
npm install headroom-ai
pip install "headroom-ai[proxy]"
headroom proxy --port 8787
3. 编程 Agent 零代码接入
uv tool install --python 3.13 "headroom-ai[all]"
headroom wrap claude
配置说明
- 离线与零依赖：进程内运行，无需 API key，也无需下载模型。设置环境变量
HEADROOM_OFFLINE=1可实现完全零网络运行。 - 消息压缩范围：默认仅压缩 tool 和 assistant 消息，保留 user 消息不变；如需一并压缩用户消息，可在调用时传入参数
compress_user_messages=True。 - 更多高级配置与参数说明，此部分原文未说明，请查看原仓库或官方文档（
https://docs.headroomlabs.ai/docs）。
常见问题
此部分原文未说明，请查看原仓库。
原始 README 摘录（英文原文，节选前 3000 字符）
<div align="center"> <img src="https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/.github/assets/hero.svg" alt="Headroom — the context compression layer for AI agents. A 55,957 token agent prompt compresses to the 24,340 tokens actually sent to the model, and the FATAL line at item 67 survives byte for byte." width="880"> <a href="https://trendshift.io/repositories/20881" target="_blank"><img src="https://trendshift.io/api/badge/repositories/20881" alt="headroomlabs-ai/headroom | Trendshift — #1 Repository Of The Day" width="250" height="55"/></a> <p> <a href="https://github.com/headroomlabs-ai/headroom"><img src="https://img.shields.io/github/stars/headroomlabs-ai/headroom?style=flat&color=00F0B5&labelColor=0C1118&label=stars" alt="GitHub stars"></a> <a href="https://github.com/headroomlabs-ai/headroom/actions/workflows/ci.yml"><img src="https://github.com/headroomlabs-ai/headroom/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://pypi.org/project/headroom-ai/"><img src="https://img.shields.io/pypi/v/headroom-ai.svg?color=00F0B5&labelColor=0C1118&label=pypi" alt="PyPI"></a> <a href="https://www.npmjs.com/package/headroom-ai"><img src="https://img.shields.io/npm/v/headroom-ai.svg?color=00F0B5&labelColor=0C1118&label=npm" alt="npm"></a> <a href="https://huggingface.co/chopratejas/kompress-v2-base"><img src="https://img.shields.io/badge/model-kompress--v2--base-65D8FF?labelColor=0C1118" alt="Model"></a> <a href="https://docs.headroomlabs.ai/docs"><img src="https://img.shields.io/badge/docs-online-00F0B5?labelColor=0C1118" alt="Docs"></a> <a href="https://github.com/headroomlabs-ai/headroom/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-98A4B3?labelColor=0C1118" alt="License"></a> </p> <p> <b><a href="https://docs.headroomlabs.ai/docs/quickstart">Quickstart</a></b> · <b><a href="#headroom-for-teams">Headroom for Teams</a></b> · <a href="#get-started-60-seconds">Install</a> · <a href="#proof-measured-token-savings">Proof</a> · <a href="#agent-compatibility">Agents</a> · <a href="https://docs.headroomlabs.ai/docs">Docs</a> · <a href="https://discord.gg/yRmaUNpsPJ">Discord</a> · <a href="https://github.com/headroomlabs-ai/headroom/blob/main/llms.txt">llms.txt</a> </p> <sub><b>AI agents / LLMs:</b> read <a href="https://github.com/headroomlabs-ai/headroom/blob/main/llms.txt"><code>/llms.txt</code></a> here, or fetch <a href="https://docs.headroomlabs.ai/llms.txt">the live index</a> · <a href="https://docs.headroomlabs.ai/llms-full.txt">full docs blob</a>.</sub> </div> <!-- mcp-name: io.github.headroomlabs-ai/headroom --> **Headroom** (`headroom-ai` on PyPI and npm) compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fewer input tokens. Measured: 21–57% fewer input tokens on four agent scenarios, 90%+ on repeated JSON arrays and log lines, little on prose ([Pr阅读完整原文
商业机会分析 AI 生成
团队级 AI 成本优化网关与看板 (SaaS/On-Premise)
| 产品构想 | 基于项目 Proxy 模式包装为多租户管理网关，统一接管团队内所有 Agent 的出站请求，提供集中化 Token 节约数据大盘与路由审计。 |
| 核心功能 | 集中式代理配置与分发、实时 Token 节约折现统计、团队级压缩规则统一下发、日志审计与合规导出、异常解压回滚机制。 |
| 目标用户 | 拥有 10 人以上 AI 研发团队的技术主管、CTO、LLM 账单管理人员。 |
| 难度/周期 | 中等 · 4-6 周 · 成本：低（基础云主机、代理转发网络带宽） |
| 收费模式 | 按接入坐席/团队月度订阅，或按已节省 Token 价值的固定百分比抽成（推测）。 |
| 竞争风险 | 自建代理可能引入额外网络延迟；注重数据隐私的企业更倾向自行部署开源版本。 |
| 依据 | 数据支持的判断 |
开发者本地桌面优化中控台 (Headroom GUI)
| 产品构想 | 针对 Cursor、Claude Code、Aider 等本地编码 Agent 用户，打造无需配置命令行的桌面客户端，一键注入并直观展示省钱数据。 |
| 核心功能 | 菜单栏常驻一键 Wrap/Unwrap、可视化实时省钱账单、预设压缩模式切换（代码/日志/宽松/激进）、本地跨 Agent 共享上下文管理面板。 |
| 目标用户 | 日常高频使用 AI 编程工具、依赖自身 API 额度付费的独立开发者与程序员。 |
| 难度/周期 | 较低 · 2-3 周 · 成本：极低（主要是跨平台桌面端打包与证书费用） |
| 收费模式 | 买断制 License（推测 $19-$39）或提供增值高级特性订阅。 |
| 竞争风险 | 纯极客用户对 CLI 接受度极高，桌面客户端付费意愿可能偏弱（推测）。 |
| 依据 | 已验证事实 |
DevOps/SRE 领域专用智能排障压缩加速包
| 产品构想 | 针对微服务海量日志和链路追踪数据，提供针对特异性日志格式（K8s, Datadog, Prometheus）的无损提取与极限压缩微服务模块。 |
| 核心功能 | 特定日志结构专有压缩算子、报错关键堆栈（如 FATAL/ERROR）无损锁定、PII 敏感脱敏过滤、超高吞吐 Docker 部署镜像。 |
| 目标用户 | 构建内部智能排障 Agent、告警根因分析机器人的 SRE/DevOps 团队。 |
| 难度/周期 | 较高 · 8-10 周 · 成本：中等（需大量垂直日志语料测试与算法调优） |
| 收费模式 | 企业商用授权按实例计费，或作为排障 Agent 的外挂插件销售服务费。 |
| 竞争风险 | 垂直场景异构数据格式多，算法泛化能力若不足会导致 LLM 理解错误（推测）。 |
| 依据 | AI推测 |
AI 基于仓库公开数据分析生成，含推测成分，不构成收益承诺。
报告会保存到 个人中心
竞品与相似项目 GitHub Search 真实检索
| 项目 | 中文简介 | Stars | 语言 |
|---|---|---|---|
| morluto/rea | 借助智能体进行逆向工程，分析应用行为甚至原生二进制文件。 | 449,667 | TypeScript |
| mattpocock/skills | 面向工程师的实用技能集合，提取自作者的 .agents 目录。 | 320,781 | Shell |
| obra/superpowers | 一套实用的智能体技能框架与软件开发方法论。 | 315,687 | Shell |
| affaan-m/ECC | 面向 Claude Code 等工具的智能体性能优化与技能强化系统。 | 300,724 | JavaScript |
| NousResearch/hermes-agent | 一款能与用户共同成长的智能体。 | 262,414 | Python |
| anomalyco/opencode | 开源的代码编写智能体。 | 225,884 | TypeScript |
以上为通过 GitHub 官方 Search API 检索的相似项目，功能差异与优劣势需进一步人工确认，配置 AI 后可生成对比分析。
项目优势与风险
| 技术成熟度 | 创建于 ，最近推送 ，发布过 100 个 Release |
| 社区活跃 | Star 79,377 / Fork 0 / Issue 0（数据支持，可自行核实） |
| 许可证 | 未检测到（需人工确认） |
| 主要风险 | 上游项目方向可能变化；同赛道竞争者较多（见竞品表）；热度与需求不完全等价 |
安装与使用
快速开始（以仓库 README 为准）
git clone https://github.com/headroomlabs-ai/headroom.git cd headroom docker compose up -d # 或参考 README 中的 docker run 命令
术语说明：Docker＝应用容器（把程序和依赖打包运行）；API Key＝调用外部服务的密钥；Git Clone＝把仓库代码下载到本地。常见错误：API Key 未配置 / 端口占用 / 数据库连接失败，多数项目在 README 的 Troubleshooting 章节有说明。