mcpField
H
headroom

headroom

github.com/l3ad3r1Agent 工作流077 次安装15 周前更新
代码仓库

关于 headroom

headroom 是用于压缩 Agent 上下文的工具，面向需要减少发送给 LLM 的内容量的开发者。它可识别 JSON、代码和文本，并通过本地缓存按需取回原文。

主要功能

  1. 01压缩工具输出和对话历史
  2. 02识别 JSON、代码和文本
  3. 03本地缓存原文并按需取回
  4. 04查看压缩与令牌节省统计
  5. 05提供 CLI 和 MCP 服务

适用场景

  1. 01缩减冗长日志进入上下文的体积
  2. 02压缩搜索结果和大型文件
  3. 03需要原文时再取回完整内容

MCP 相关

headroom MCP 服务向客户端提供内容压缩、原文取回和统计工具。通过 headroom mcp install 注册，或运行 headroom mcp serve 启动。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/l3ad3r1/hermes-skills --skill headroom

安装后在 Claude Code 中输入/headroom确认已加载。

附带文件NOTICE.md

详细介绍

Headroom

面向 AI Agent 的上下文压缩——在保留含义的同时，将发送给大模型的 token 减少 60–95%。在工具输出、日志、搜索结果、RAG 片段、文件和对话历史到达模型之前对其进行压缩。它会自动检测内容类型（JSON / 代码 / 文本），并支持 CCR（Compress-Cache-Retrieve）：原始内容缓存在本地，按需获取。

上游项目：headroom，由 chopratejas 开发（Apache-2.0）；在 PyPI 上发布为 headroom-ai。

何时使用

  • 工具或命令返回大量内容（冗长日志、大型 JSON、很长的文件列表、搜索结果、大文件），可能会使上下文窗口膨胀。
  • 用户要求压缩上下文、缩减负载或节省 token。
  • 在大量内容进入上下文之前进行压缩。

设置

pip install "headroom-ai[mcp]"      # or [all] for every compressor / extra

注册 MCP 服务（提供 headroom_compress / headroom_retrieve / headroom_stats）：

headroom mcp install        # auto-configures detected coding agents
# or run the server directly: headroom mcp serve

如需对所有流量进行完全自动压缩，请运行代理并让客户端连接到它。这会通过本地代理路由每个 API 请求，因此请谨慎启用：

headroom proxy --port 8787
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

工具（MCP，显示为 mcp__headroom__*）

  • headroom_compress — 压缩一段上下文/内容
  • headroom_retrieve — 获取未压缩的原始内容（CCR）
  • headroom_stats — 压缩统计信息 / token 节省量

对大型输出使用 headroom_compress，将压缩后的摘要保留在上下文中；仅在确实需要完整原始内容时才调用 headroom_retrieve。

CLI 附加命令：headroom perf（节省量）、headroom output-savings、 headroom learn --verbosity、headroom update。环境变量开关： HEADROOM_OUTPUT_SHAPER=1、HEADROOM_UPDATE_CHECK=off、HF_HUB_OFFLINE=1。

安装说明和已知问题

Windows 源码构建会失败——请改在 WSL2 中安装。 headroom-ai 包含一个 Rust 扩展（crates/headroom-py，通过 maturin/cargo 构建）。Windows 上没有适用于近期 Python 版本的预编译 wheel，因此 pip/uv 会退回到从源码编译——如果 GNU link（来自 Git / coreutils）遮蔽了 MSVC 的 link.exe 链接器，就会失败（link: extra operand → could not compile target-lexicon → maturin failed）。与其费力排查 Windows Rust 工具链，不如在 wheel 可以顺利构建的 Linux 环境中安装：

# inside WSL2 Ubuntu (no sudo needed):
curl -LsSf https://astral.sh/uv/install.sh | sh      # if uv isn't present
uv tool install "headroom-ai[mcp]"                   # -> ~/.local/bin/headroom

然后，在 Windows 客户端中通过 WSL 封装来注册 MCP 服务：

claude mcp add-json headroom \
  '{"command":"wsl.exe","args":["-d","Ubuntu","-e","bash","-lc","export PATH=$HOME/.local/bin:$PATH; exec headroom mcp serve"]}' \
  --scope user

在 Linux/macOS 上，直接运行 pip install "headroom-ai[mcp]" 即可——跳过 WSL 封装，直接注册 headroom mcp serve。

致谢

上游项目：headroom，由 chopratejas 开发（Apache-2.0）；在 PyPI 上发布为 headroom-ai。此技能 用于说明上游工具并将其接入 Agent Skills 格式；源码未随附——请从 PyPI / 上游仓库安装。

此技能由 Rinu（l3ad3r1）与 Claude（Anthropic）合作编写。

评论

支持 Markdown