tool-notes/claude-hud-notes.md

Claude HUD 安裝與使用筆記

基本資訊

• 專案: https://github.com/jarrodwatts/claude-hud
• 作者: Jarrod Watts
• 授權: MIT
• 類型: Claude Code 外掛（statusline 增強）
• 用途: 在 Claude Code 終端狀態列即時顯示 context 用量、執行中的工具／agent、待辦進度、git 狀態等資訊
• 需求: Claude Code v1.0.80+、Node.js 18+ 或 Bun
• 本機環境: Claude Code 2.1.114、Node v25.8.2、Bun 1.3.11 ✅
• 安裝日期: 2026-04-19

是什麼

Claude HUD 把原本單純的 statusline 變成 HUD（Heads-Up Display），即時顯示：

• Project path：可顯示 1–3 層目錄
• Context 健康度：context window 用量長條，顏色會隨用量變化
• Tool activity：正在跑的 Read/Edit/Grep 等工具與次數
• Agent 追蹤：活躍 subagent 名稱、模型、耗時
• Todo 進度：任務完成比例
• Git 狀態：branch、dirty、ahead/behind、檔案變更數
• Usage limits：Claude 訂閱用戶的每小時與 7 日配額

安裝步驟

在 Claude Code 對話中依序執行：

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/reload-plugins
/claude-hud:setup

接著重新啟動 Claude Code，讓 statusLine 設定生效。

平台注意事項

• Linux：若 install 時出現 cross-device link 錯誤，先設定 TMPDIR=~/.cache/tmp 再安裝。
• Windows：若 setup 提示找不到 JavaScript runtime，請先裝 Node.js LTS。
• macOS：無額外步驟。

設定

互動式設定：

/claude-hud:configure

或直接編輯：

~/.claude/plugins/claude-hud/config.json

預設 Preset

Preset	內容
Full	全部資訊開啟
Essential	activity + git，少雜訊
Minimal	只顯示模型名稱與 context bar

可調整項目

• 語言：英文 / 中文
• 版面：多行展開 或 單行緊湊
• Path 深度：1–3 層
• Git 顯示：dirty、ahead/behind、變更檔案數
• 顯示切換：tools、agents、todos、duration、memory、cost
• 配色：16 個顏色值可自訂

顯示範例

預設兩行版面：

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

啟用 activity 行（選用）：

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)

常用檢查與移除

# 檢查外掛目錄
ls ~/.claude/plugins/marketplaces/claude-hud 2>/dev/null

# 檢查設定
cat ~/.claude/plugins/claude-hud/config.json 2>/dev/null

在 Claude Code 中移除：

/plugin uninstall claude-hud
/plugin marketplace remove jarrodwatts/claude-hud

備註

• HUD 資料來自 Claude Code 的 statusLine hook，因此需要重啟 Claude Code 才會套用新的 statusLine 配置。
• 若 context bar 顯示與 /context 略有落差，屬預期：HUD 讀的是 hook 傳入的近似值。
• 多行版面在較窄的終端（寬度 < 80）可能換行，建議改用 compact 或 minimal preset。