headroom：给 Claude Code 加状态栏，实时看清上下文窗口还剩多少

headroom 项目仓库名为 henchmarketing-rgb/headroom，完整 GitHub 链接 https://github.com/hbenchmarketing-rgb/headroom，主要语言 Shell，stars 66，forks 4，许可 MIT License，最近 push 日期 2026-04-24，数据抓取日期 2026-06-08。本文数据基于抓取日期，后续以 GitHub 当前页面为准。它通过读取 Claude Code 实际 session JSONL，在状态栏显示实时上下文使用进度条，帮助用户判断是否需要 compact 或重启。

项目速览

headroom 的仓库名是 henchmarketing-rgb/headroom，完整链接 https://github.com/hbenchmarketing-rgb/headroom，语言为 Shell，stars 66，forks 4，许可 MIT License，最近 push 日期 2026-04-24，数据抓取日期 2026-06-08。README 描述它读取实际 session JSONL 而非估算，支持多目录隔离。以上数字为抓取日期数据，后续以 GitHub 当前页面为准。

它解决什么问题

Claude Code 会话中突然触发 compaction 会导致工作进度丢失，用户往往没有预警。headroom 通过 PostToolUse hook 实时更新状态栏进度条，读取真实 JSONL token 用量而非环境变量估算，切换模型时仍保持准确。它仅针对 Claude Code，不适用于其他 LLM 客户端。

为什么这个项目值得关注

从当前抓取数据看，它直接针对 Claude Code 用户最常见的上下文窗口痛点，MIT 许可和 Shell 实现让安装脚本简单。stars 数量不高但功能聚焦，适合解决特定问题而非通用工具。

核心能力与工作原理

它在每次 Bash、Agent 或 Write 调用后读取项目目录下最新 session JSONL，状态栏显示 live bar 并支持 per-directory 隔离。README 提到支持手动安装和一键 curl 安装两种方式。

工具选择决策框架

新手优先看是否经常在 Claude Code 中遇到上下文丢失，想省时间看一键安装是否能接受。预算有限看完全免费且本地运行，专业用户看是否需要跨模型跨目录的精确 token 追踪。不使用 Claude Code、已通过其他方式监控上下文或需要商业支持的情况不建议用。

适合人群与使用场景

适合 Claude Code 重度用户、需要长时间多轮对话的开发者。使用场景包括写长代码、重构大型项目、需要保留完整历史上下文的调试会话。不适合仅偶尔使用或已习惯手动 compact 的用户。

普通用户怎么开始

普通用户可参考 README 提供的 curl 一键脚本方式，安装后重启 Claude Code，状态栏自动出现进度条，无需额外配置。

风险与选型提醒

stars、forks、push 日期均为抓取日期 2026-06-08 的快照。MIT 许可下可自由使用，但商业使用前查看 LICENSE。目前维护状态以最近 push 日期为参考，后续以仓库实际更新为准。

替代项目与下一步找工具

同类上下文管理方向还有其他工具，读者可前往 nav-ai.cn 的 AI 开发工具或智能体分类查看更多 Claude 相关开源项目。下一步可直接访问 AI 工具大全或 AI 新手入门，按任务场景筛选合适选项。

常见问题

headroom 安装后状态栏不显示怎么办

检查是否已重启 Claude Code，并确认 hook 已正确放置，具体以仓库 README 为准。

headroom 是否会读取我的对话内容

它仅读取 session JSONL 中的 token 用量数据，不读取完整对话内容。

Claude Code 更新后 headroom 还会生效吗

更新后需重新测试 hook 是否兼容，建议查看仓库最新 push 日期确认维护状态。

有没有支持其他 LLM 的类似工具

nav-ai.cn 的 AI 开发工具分类中可筛选其他上下文监控项目。

结语

headroom 针对 Claude Code 的上下文窗口痛点提供了简单可视化方案，适合重度用户判断是否值得尝试。继续在 nav-ai.cn 查看 AI 工具大全、AI 新手入门或按副业场景筛选更多开发工具。