---
slug: claude-hud-claude-code-usage-limits
title: "Claude HUD 安裝與設定：在 Claude Code 直接看 5 小時與每週額度"
status: published
excerpt: "用 Claude HUD 把 Claude Code 提供的 5h 與 weekly rate-limit 視窗放進 statusline：安裝、設定、刷新與資料邊界一次整理。"
category: AI
tags: [claude-code, cli, developer-tools, usage-limits]
author: Seer
author_role: Author
read_time: 7 min
cover: "/static/claude-hud-claude-code-usage-limits-cover.png"
closing_note: "看得到剩餘額度，不是為了把工作塞滿，而是知道什麼時候該停。"
published_at: "2026-09-01T00:54:00Z"
updated_at: "2026-09-01T00:54:00Z"
---


[Claude HUD](https://github.com/jarrodwatts/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]

正常畫面會接近這樣：

```text
[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 裡依序輸入：

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

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

```bash
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 都固定出現

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

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

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

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

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

```json
{
  "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]

## Sources

- [1：Claude HUD official repository metadata](https://github.com/jarrodwatts/claude-hud)
- [2：Claude HUD README at inspected commit](https://github.com/jarrodwatts/claude-hud/blob/939eb66485832dead1b0a28a954f76f7aa2bdb06/README.md)
- [3：Claude HUD plugin manifest v0.8.0](https://github.com/jarrodwatts/claude-hud/blob/939eb66485832dead1b0a28a954f76f7aa2bdb06/.claude-plugin/plugin.json)
- [4：Claude HUD setup command contract](https://github.com/jarrodwatts/claude-hud/blob/939eb66485832dead1b0a28a954f76f7aa2bdb06/commands/setup.md)
- [5：Claude HUD statusline rate-limit parsing](https://github.com/jarrodwatts/claude-hud/blob/939eb66485832dead1b0a28a954f76f7aa2bdb06/src/stdin.ts)
- [6：Claude HUD 5h and weekly rendering logic](https://github.com/jarrodwatts/claude-hud/blob/939eb66485832dead1b0a28a954f76f7aa2bdb06/src/render/lines/usage.ts)
- [7：Claude HUD runtime data flow and external snapshot fallback](https://github.com/jarrodwatts/claude-hud/blob/939eb66485832dead1b0a28a954f76f7aa2bdb06/src/index.ts)
- [8：Claude HUD v0.8.0 release](https://github.com/jarrodwatts/claude-hud/releases/tag/v0.8.0)