Claude HUD 安裝與設定：在 Claude Code 直接看 5 小時與每週額度

Claude HUD 的重點是把 Claude Code 已經提供給 statusline 的 session 資訊，放到輸入框下方持續顯示。本文要處理的事情很具體：安裝這個 plugin，讓 Claude Code 在有提供 subscriber rate_limits 時，直接顯示目前 5 小時與每週用量、重置時間，以及 context、工具活動和待辦進度。

你會拿到四件事：正確的 marketplace 安裝順序、怎麼把 weekly 從預設的 80% 門檻改成每次都顯示、一份適合繁中／24 小時制的設定範例，以及「明明裝好了卻看不到額度」時要先查哪一層。這篇真正關注資料來源與設定副作用：數字由 Claude Code statusline payload 提供；setup 會處理 statusLine，原本已有其他 statusline 的人要先決定是否取代。

先講結論：你用 Claude 訂閱方案、平常就在 terminal 裡跑 Claude Code，又想知道 5h 還剩多少與 weekly 何時要撞線，Claude HUD 值得裝。 先用預設 setup，接著把 sevenDayThreshold 設成 0，讓 weekly 永遠出現。若你是 API key-only、Bedrock，或目前的 Claude Code session 沒送出 rate_limits，裝好後仍可能沒有額度列；這通常表示 HUD 未收到可顯示的來源資料。[1][2]

Claude HUD 顯示的是什麼

它是一個 Claude Code plugin，不是獨立 terminal dashboard。它接在 Claude Code 原生 statusline 流程：Claude Code 把 JSON 經 stdin 交給 HUD，HUD 輸出幾行文字，Claude Code 再畫在輸入區下方。除了 model、專案路徑、git、context 之外，它也會從本輪資料中的 rate_limits.five_hour 與 rate_limits.seven_day 讀取已用比例和 reset timestamp。[2][5]

正常畫面會接近這樣：

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (resets in 1h 30m) | Weekly ██████████ 85% (resets in 2d)

這裡有兩個常被混在一起的數字：

欄位	代表什麼	HUD 的角色
Context	目前這個對話塞進 context window 的程度	顯示 Claude Code 提供的 token／context 資訊
5h	訂閱者目前 5 小時 rate-limit 視窗的已用比例	顯示 `rate_limits.five_hour`
Weekly / 7d	訂閱者目前 7 天 rate-limit 視窗的已用比例	顯示 `rate_limits.seven_day`，或在滿足顯示門檻時出現

所以它適合回答「我現在還能不能繼續用這個 session」與「這週額度快不快碰到上限」，不適合拿來當帳單系統或跨帳號用量稽核。HUD 只轉譯眼前 session 收到的資料；額度是否存在、數值是否回傳，仍由 Claude Code 與訂閱端決定。[5][6]

安裝：先交給 Claude Code 的 plugin 機制

在 Claude Code 互動 session 裡依序輸入：

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

也可以從一般 shell 先完成 marketplace 與安裝：

claude plugin marketplace add jarrodwatts/claude-hud
claude plugin install claude-hud@claude-hud

接著回到 Claude Code session 執行 /reload-plugins，再執行 /claude-hud:setup。plugin manifest 的版本是 0.8.0；本次檢查的 main commit 是 939eb66485832dead1b0a28a954f76f7aa2bdb06，最新 release 也是 v0.8.0。[2][3][8]

setup 會做什麼，為什麼別跳過

/claude-hud:setup 不只是問你要不要顯示顏色。它會找出 plugin 的實際安裝位置與 Node.js／Bun runtime，產生 statusline launcher，然後把 command 寫進 active Claude config directory 的 settings.json。

如果你已經有 Starship 以外的 Claude Code statusline、自己寫的 statusline script，或另一個 HUD，這一步要停下來看。setup 的設計會先備份 settings.json，辨識既有 statusLine.command；若不是它自己的 command，流程應先問你要取代還是保留。這是因為 Claude Code 的 statusLine 是同一個設定位置，不能期待兩套 command 自動串接。[4]

macOS／Linux 需要 Node.js 18+ 或 Bun；Windows 支援 Node.js 18+。正常完成後，Claude Code 應在下一次 interaction 重載設定並畫出 HUD；較舊版本若沒有出現，再完全重開 Claude Code。[2]

讓 5h 與 weekly 都固定出現

安裝完成後，主要設定檔在：

$CLAUDE_CONFIG_DIR/plugins/claude-hud/config.json

沒有設定 CLAUDE_CONFIG_DIR 時，通常就是：

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

先用 /claude-hud:configure 走一次互動設定，選繁體中文與你想要的 layout。接著若你希望 statusline 專注看額度，手動合併以下設定：

{
  "language": "zh-Hant",
  "lineLayout": "expanded",
  "display": {
    "showUsage": true,
    "usageCompact": true,
    "usageValue": "remaining",
    "sevenDayThreshold": 0,
    "timeFormat": "both",
    "hourCycle": "h23"
  }
}

這組設定的重點：

showUsage: true：保留 usage 列。它在目前版本預設本來就開啟，明寫是為了避免日後自己調 preset 後忘掉。
usageCompact: true：縮成 5h: 25% (1h 30m)，在窄 terminal 比 bar 更容易掃到。
usageValue: remaining：將百分比改成剩餘量。例如原本已用 25%，改成顯示剩餘 75%。
sevenDayThreshold: 0：weekly 永遠顯示。預設門檻是 80%，低於門檻時只看得到 5h，很多人會誤以為 weekly 壞了。
timeFormat: both：同時顯示倒數與實際重置時間。
hourCycle: h23：固定以 24 小時制顯示 reset time，避免 terminal locale 切換後又回到 AM／PM。

如果你習慣看已用比例，把 usageValue 改回 percent 即可。每週只想在快用完時才顯示，則移除 sevenDayThreshold 或設回預設的 80。[2][6]

想讓 reset 倒數在空檔也會動：加 5 秒刷新

Claude Code 預設在有 interaction 時才會重跑 statusline，例如 Claude 完成一個回應、/compact 結束或切換 permission mode。你停在 terminal 前不輸入時，HUD 上的倒數不會自行更新。

/claude-hud:setup 會提供 auto-refresh 選項。建議選 5 秒，它會把 refreshInterval: 5 合併到現有的 statusLine object。這是足夠看 reset time 的頻率，也避免每秒都重新啟動 runtime、讀 transcript 與檢查 git。若你沒有開啟 timer，數字仍會在下次 interaction 更新，只是中間的倒數會停在上一個值。[2][4]

不要直接把一個示範 command 覆蓋到 settings.json。statusline command 是 setup 依照安裝位置與 runtime 產生的；你手動調整時只加 refreshInterval，保留既有 type 與 command。

看不到 usage 時，先依這個順序排查

1. 先確認你看的不是 API-key-only 或 Bedrock session

Claude HUD README 將 subscriber rate limits 列為顯示前提。API-key-only 使用者走的是 token 計費，沒有這組訂閱限額可顯示；Bedrock session 也會隱藏 usage。這兩種情況調 config.json 不會變出 5h／weekly。[2][5]

2. 送出一則訊息後再看

Claude Code 可能在 session 第一次 model response 前仍讓 rate_limits 保持空白。先送一則正常訊息，等回覆完成後看 HUD；如果設定剛寫入，下一次 interaction 也是觸發 statusline 的時機。[2][5]

3. weekly 沒顯示，先查門檻而非重裝

sevenDayThreshold 預設是 80。你若只有 20% weekly usage，正常情況下它會被隱藏。把值設成 0 後重送一則訊息測試。若還是沒有，代表本輪 payload 可能沒有 seven_day，HUD 不會自行補算一個數字。[2][6]

4. HUD 整條都沒有出現，再查 statusLine 與 runtime

先執行 /claude-hud:setup 重新檢查。它的診斷流程會確認 plugin cache、runtime 絕對路徑、settings.json 的 statusLine.command，並嘗試執行生成 command。macOS 上用 nvm、mise 或 asdf 的人，Node／Bun 的路徑變動後也可能使舊 command 失效。[4]

資料與安全邊界：這是 statusline renderer，不是額度爬蟲

Claude HUD 的安全模型值得寫清楚。README 將它描述為 local-only：不發 network request、不抓 credential、不呼叫 undocumented Claude API。它讀取的是 Claude Code 給它的 stdin、現有 session transcript path、部分 Claude 設定檔與目前 workspace 的 git metadata。專案也把自己的 cache 或可選 snapshot 設計為 POSIX private permissions。[2][7]

它有一個 externalUsagePath 選項，能讀取本地 JSON snapshot 當 fallback。這是給本地 sidecar 或其他工具接資料用，不是一般使用者安裝 Claude HUD 的必要步驟。正常狀況先看 Claude Code stdin；只有 stdin 缺資料時，才考慮是否真的需要自己維護 snapshot。

另外，--extra-cmd 只有在 HUD process 設定 CLAUDE_HUD_ALLOW_EXTRA_CMD=1 等值後才可執行。它會在 statusline refresh 用你的使用者權限跑 shell command。這項功能和看額度無關；除非你知道自己在做什麼，保持關閉即可。[2]

我會怎麼配

我會先跑 /claude-hud:setup，確認它有備份既有 statusline，再使用下面的取向：

需要快速判斷能不能繼續長跑：usageValue: remaining、sevenDayThreshold: 0。
terminal 很窄：開 usageCompact。
需要估計 reset 的確切時間：timeFormat: both、hourCycle: h23，並選 5 秒 refresh。
很在意 terminal 乾淨：維持 minimal preset，但另外把 showUsage 打開。

Claude HUD 解決的是「每次要打 /usage 或猜剩餘額度」這個摩擦。它把現有 statusline payload 變成一眼可讀的操作資訊。前提也很明確：Claude Code 必須真的給出 subscriber rate_limits。有資料時它很順；沒有資料時，最正確的行為是空白，不是假造一個看似精準的額度條。

查核範圍

功能、安裝步驟、設定鍵與資料邊界皆以 Claude HUD 官方 repository 的 main commit 939eb66485832dead1b0a28a954f76f7aa2bdb06 為準，對應 release v0.8.0。Claude Code 提供的 session payload 會隨方案、登入方式與版本改變，實際畫面仍應以你自己的 session 為準。[1][8]