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