用途：Headroom 是传输层，负责在新鲜工具输出与新对话轮次到达模型前做压缩；它不替代源码导航、代码审查或模型自身的上下文计量。
主要能力与使用方式：安装时使用支持代理、MCP 与代码感知压缩的最小上游扩展集，在 macOS Apple Silicon 与 Linux 上用 uv 隔离：uv tool install --python 3.13 'headroom-ai[proxy,mcp,code]'，随后可执行 headroom --version、headroom deploy、headroom install status、headroom doctor。headroom deploy 会选择持久本地运行时、配置检测到的受支持客户端，并在 127.0.0.1:8787 启动代理；install status 与 doctor 是证据门槛，仅有 PATH 上的二进制不算客户端已被路由。Windows 在文档所述发布线没有预编译 wheel，需先安装文档规定的 MSVC 与 Rust 前置依赖。运行模式包括：持久自动路由 headroom deploy、健康诊断 headroom doctor、单会话包装 headroom wrap claude、按需 MCP 工具 headroom mcp install、手动本地代理 headroom proxy --mode cache。
代码工作策略：可选 Claude Code 钩子 scripts/jeo-code-policy-hook.py 仅作用于源文件 Edit 与 Write；会话首次源变更时运行只读预检 graphify scope <cwd>、对已有图运行 graphify check-update <cwd> 及 headroom doctor，并拒绝该次尝试给出重试指引。仅当宿主钩子负载显式包含有效 context_usage_percent >= 60 时，才额外拒绝一次并要求 Ponytail 阶梯；宿主不暴露该确切百分比时不得推断。可通过 bash ./scripts/setup-claude-code-policy-hook.sh --dry-run 与去掉 --dry-run 安装适配器；自检命令为 python3 scripts/jeo-code-policy-hook.py --self-test。
限制与不适用：仅需源码或符号发现时应使用 graphify 或 codebase-search；仅需代码体积缩减审查且无上下文策略时使用 ponytail；通用智能体配置归属使用 agent-configuration。应只保留一条运行时路径，避免重复代理；凭据与提供商配置放在项目之外；context_usage_percent 不得估算。