Claude Code 终端状态栏 HUD 工具

解决什么

Claude Code 终端用户在命令行交互时缺乏直观的状态反馈。best-claude-hud 在终端底部提供持久化状态栏,实时展示当前使用的 Claude 模型、推理强度(reasoning effort)、工作目录、Git 分支与状态、上下文窗口占用率等关键信息。相比频繁手动查询,状态栏让开发者始终掌握会话状态,避免超出上下文限制或误操作分支。

为何火

该项目在 GitHub 获得 1065 stars,核心优势在于:用 Rust 实现的高性能渲染,通过 npm 分发预编译二进制(用户无需安装 Rust 工具链),一行命令完成安装与 Claude Code 配置。支持 Windows/macOS/Linux 全平台,提供 8 种内置主题(包括 Gruvbox、Nord、Tokyo Night 等流行配色),并允许用户自定义主题和分段显示。对 Nix 用户友好,提供 flake 声明式配置,契合现代开发者工具链需求。

核心功能

• 模型与推理显示: 自动识别 Claude 模型家族,实时显示推理强度(reasoning effort)
• Git 集成: 显示分支名、clean/dirty/conflict 状态、ahead/behind 提交数
• 上下文窗口监控: 读取 Claude Code 官方 statusLine 数据,回退到 active-transcript 解析,可视化窗口占用
• 可选分段: 用量/速率限制、成本、会话信息、输出风格等模块可按需启用
• TUI 配置界面: 运行 --config 进入交互式配置,无需手动编辑 TOML 文件
• 主题系统: 8 种内置主题,支持 ~/.claude/best-claude-hud/themes/ 自定义主题
• 自动更新检测: 后台检查新版本,可在配置中关闭

安装

一键安装并配置 Claude Code:

npm install -g best-claude-hud@latest && best-claude-hud --setup

国内用户使用镜像:

npm install -g best-claude-hud@latest --registry https://registry.npmmirror.com && best-claude-hud --setup

安装后需重启 Claude Code 生效。--setup 命令会自动修改 ~/.claude/settings.json,添加 statusLine 配置块并保留现有设置。

Nix 用户可通过 flake 安装:

nix profile install github:GaoSSR/best-claude-hud
best-claude-hud --setup

或在 home-manager 中声明式管理(需完整接管 settings.json,不适合已有手动配置的用户)。

适合谁

• Claude Code 重度用户: 在终端中频繁使用 Claude Code,需要实时状态反馈
• 多分支开发者: 需要随时确认当前 Git 分支和同步状态
• 上下文敏感场景: 处理大型代码库时需监控上下文窗口占用,避免超限
• Nix/NixOS 用户: 提供官方 flake,可纳入声明式系统配置
• 主题爱好者: 内置 8 种主题,支持自定义配色和分段布局

不适合纯 GUI IDE 用户或不使用 Claude Code 的开发者。

社区评价

暂无足量社区公开讨论,以下为基于项目本身的中立评估:

项目创建于 2026 年 6 月,一个月内快速迭代至 v0.1.10,显示出活跃的维护节奏。1000+ stars 表明在 Claude Code 用户群体中获得认可。技术选型(Rust + npm 分发)兼顾性能与易用性,通过 Kiri-style npm alias optional dependencies 自动匹配平台二进制,降低安装门槛。提供 Nix flake 和 TUI 配置界面,体现对现代开发工具链的适配。

项目文档完善,提供英文、简体中文、日文三语 README,国内用户可用 npmmirror 镜像,体现国际化和本地化意识。

选型对比

vs 手动查询 Git/上下文: 手动运行 git status 或查看 Claude Code 输出需中断工作流,状态栏持久化显示无需额外操作。

vs Starship 等通用提示符工具: Starship 侧重 shell 提示符美化,不感知 Claude Code 内部状态(如推理强度、上下文窗口)。best-claude-hud 专为 Claude Code 设计,直接读取其 statusLine API 和 active-transcript 数据。

vs 自建脚本: 自建需处理跨平台兼容性、Claude Code API 解析、主题渲染等,best-claude-hud 开箱即用且持续更新适配 Claude Code 变化。

取舍:仅适用于 Claude Code 终端场景,不支持其他 AI 编码工具;依赖 npm 全局安装,对无 Node.js 环境的用户需额外配置。

已知坑

1. 配置生效需重启: 修改 ~/.claude/settings.json 后必须重启 Claude Code,现有会话不会自动重载
2. PATH 依赖: 手动配置 "command": "best-claude-hud" 时,需确保 Claude Code 会话继承正确的 PATH,否则建议用 --setup 写入绝对路径
3. Nix home-manager 陷阱: 文档中的 home.file 声明会覆盖整个 settings.json,已有手动配置会丢失,需先迁移所有设置到 Nix 表达式
4. 第三方模型识别: Claude 模型家族自动识别,但第三方模型需手动编辑 models.toml 配置显示名称和上下文限制
5. API 缓存: 用量 API 数据缓存在 .api_usage_cache.json,频繁查询可能遇到速率限制,可在配置中调整刷新间隔

来源: GitHub + 项目 README