# 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 對話中依序執行：

```text
/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**：無額外步驟。

## 設定

互動式設定：

```text
/claude-hud:configure
```

或直接編輯：

```text
~/.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 個顏色值可自訂

## 顯示範例

**預設兩行版面：**

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

**啟用 activity 行（選用）：**

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

## 常用檢查與移除

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

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

在 Claude Code 中移除：

```text
/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。