用途：在大型内容进入模型上下文前进行压缩，降低发送给 LLM 的 token 量，同时保留含义。适用于工具或命令返回大量日志、大 JSON、长文件列表、搜索结果、大文件等场景，或用户要求压缩上下文、缩小负载、节省 token 时。
主要能力：自动检测内容类型（JSON/代码/文本）；支持 CCR（Compress-Cache-Retrieve），原始内容本地缓存、按需取回；提供 MCP 工具 headroom_compress（压缩内容）、headroom_retrieve（取回原始未压缩内容）、headroom_stats（压缩统计与 token 节省）。
使用方式：安装 pip install "headroom-ai[mcp]"（或 [all] 安装全部压缩器/扩展）。注册 MCP 服务器：headroom mcp install 自动配置检测到的编码智能体，或直接运行 headroom mcp serve。若要对全部流量自动压缩，可运行代理并让客户端指向它：headroom proxy --port 8787，再设置 ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude。用法上，对大型输出调用 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 遮蔽 MSVC link.exe 而失败。可在 WSL2 Ubuntu 中执行 curl -LsSf https://astral.sh/uv/install.sh | sh 与 uv tool install "headroom-ai[mcp]"，再从 Windows 客户端通过 wsl.exe 包装注册 MCP 服务器。Linux/macOS 上可直接 pip install "headroom-ai[mcp]" 并注册 headroom mcp serve。上游项目为 chopratejas 的 headroom（Apache-2.0），以 headroom-ai 发布在 PyPI。