115 lines
3.1 KiB
Markdown
115 lines
3.1 KiB
Markdown
# 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。
|