Claude HUD

技能由 ara.so 提供 — Daily 2026 Skills 系列。

Claude HUD 是一個 Claude Code 外掛，可在終端機加入持續顯示的狀態列，即時呈現上下文視窗使用量、正在進行的工具呼叫、執行中的子代理程式以及待辦事項進度 — 始終顯示在輸入提示下方。

功能說明

功能	說明
上下文健康度	視覺化長條圖顯示上下文視窗使用程度（綠色 → 黃色 → 紅色）
工具活動	即時顯示檔案讀取、編輯和搜尋等操作
代理程式追蹤	顯示哪些子代理程式正在執行及其工作內容
待辦事項進度	即時任務完成追蹤
使用量限制	Claude 訂閱者的速率限制消耗
Git 狀態	目前分支、髒狀態、與遠端的前後關係

需求

Claude Code v1.0.80+
Node.js 18+ 或 Bun

安裝方式

在 Claude Code 工作階段中執行以下指令：

步驟 1：新增市集

/plugin marketplace add jarrodwatts/claude-hud

步驟 2：安裝外掛

/plugin install claude-hud

Linux 使用者：若出現 EXDEV: cross-device link not permitted，請先設定 TMPDIR：
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

步驟 3：設定狀態列

/claude-hud:setup

Windows 使用者：若設定回報找不到 JavaScript 執行環境，請先安裝 Node.js LTS：
winget install OpenJS.NodeJS.LTS

步驟 4：重新啟動 Claude Code 以載入新的 statusLine 設定。

顯示畫面

預設 2 行佈局

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

啟用選用行

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)

設定

互動式設定（建議）

/claude-hud:configure

這會開啟引導流程，提供預設選項：

預設	顯示內容
完整	全部 — 工具、代理程式、待辦事項、Git、使用量、持續時間
精簡	活動行 + Git，最少雜訊
極簡	僅模型名稱和上下文長條圖

手動設定

直接編輯 ~/.claude/plugins/claude-hud/config.json：

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "context", "usage", "tools", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": false
  },
  "display": {
    "showModel": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showUsage": true,
    "usageBarEnabled": true,
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": false,
    "showSpeed": false,
    "showConfigCounts": false,
    "showMemoryUsage": false,
    "showSessionName": false,
    "showClaudeCodeVersion": false,
    "sevenDayThreshold": 80,
    "showTokenBreakdown": true
  },
  "colors": {
    "context": "green",
    "usage": "brightBlue",
    "warning": "yellow",
    "usageWarning": "brightMagenta",
    "critical": "red",
    "model": "cyan",
    "project": "yellow",
    "git": "magenta",
    "gitBranch": "cyan",
    "label": "dim",
    "custom": "208"
  }
}

主要設定選項

佈局

{
  "lineLayout": "expanded",   // "expanded"（多行）或 "compact"（單行）
  "pathLevels": 1             // 專案路徑的目錄層級數 1-3
}

路徑層級範例：

1 → [Opus] │ my-project git:(main)
2 → [Opus] │ apps/my-project git:(main)
3 → [Opus] │ dev/apps/my-project git:(main)

上下文顯示格式

{
  "display": {
    "contextValue": "percent"    // "45%"
    // "contextValue": "tokens"  // "45k/200k"
    // "contextValue": "remaining" // "55% remaining"
    // "contextValue": "both"    // "45% (45k/200k)"
  }
}

元素順序（展開佈局）

{
  "elementOrder": ["project", "context", "usage", "memory", "environment", "tools", "agents", "todos"]
}

從陣列中移除任何項目即可完全隱藏。

Git 狀態選項

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,         // "main*" 表示未提交變更
    "showAheadBehind": true,   // "main ↑2 ↓1"
    "showFileStats": true      // "main* !3 +1 ?2"（已修改/已新增/已刪除/未追蹤）
  }
}

顏色

支援的值：命名顏色（dim、red、green、yellow、magenta、cyan、brightBlue、brightMagenta）、256 色數字（0-255）或十六進位（#rrggbb）。

{
  "colors": {
    "context": "#00FF88",
    "model": "208",
    "project": "#FF6600"
  }
}

運作原理

Claude HUD 使用 Claude Code 原生的 statusline API — 無需獨立視窗或 tmux：

Claude Code → stdin JSON → claude-hud → stdout → 終端機狀態列
           ↘ 轉錄 JSONL（即時解析工具、代理程式、待辦事項）

Token 資料直接來自 Claude Code（非估算）
可隨回報的上下文視窗大小擴展，包含 100 萬 token 的工作階段
解析轉錄檔以取得工具/代理程式活動
約每 300ms 更新一次

常見配置

專注工作用的極簡設定

{
  "lineLayout": "compact",
  "display": {
    "showModel": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showUsage": false,
    "showTools": false,
    "showAgents": false,
    "showTodos": false
  }
}

完整監控設定

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showMemoryUsage": true,
    "showConfigCounts": true,
    "contextValue": "both",
    "showTokenBreakdown": true
  }
}

始終顯示 7 天使用量

{
  "display": {
    "showUsage": true,
    "sevenDayThreshold": 0
  }
}

輸出：Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

疑難排解

設定後 HUD 未出現

完全重新啟動 Claude Code（結束並重新執行 claude）
在 macOS 上，請確保完全結束應用程式，而不只是關閉視窗

設定未生效

檢查 JSON 語法錯誤 — 無效的 JSON 會靜默回退為預設值
驗證：cat ~/.claude/plugins/claude-hud/config.json | node -e "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))"
刪除設定檔並執行 /claude-hud:configure 重新產生

Git 狀態遺失

確認你位於 git 儲存庫中（git status）
確保設定中 gitStatus.enabled 不是 false

工具/代理程式/待辦事項行未顯示

這些預設為隱藏 — 請透過 showTools、showAgents、showTodos 啟用
僅在有活動時才會顯示對應行

使用量限制未顯示

需要 Claude 訂閱帳戶（僅 API 金鑰無法使用）
AWS Bedrock 使用者會看到 Bedrock 標籤；使用量需在 AWS 主控台管理
在新工作階段中，使用量資料可能直到第一次模型回應後才會出現
較舊的 Claude Code 版本若不發出 rate_limits，則不會顯示訂閱者使用量

Linux 安裝時跨裝置錯誤

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
# 然後在該工作階段中執行 /plugin install claude-hud

Windows：找不到 JavaScript 執行環境

winget install OpenJS.NodeJS.LTS
# 重新啟動 shell，然後再次執行 /claude-hud:setup

外掛指令參考

指令	說明
`/plugin marketplace add jarrodwatts/claude-hud`	註冊外掛來源
`/plugin install claude-hud`	安裝外掛
`/claude-hud:setup`	初始設定精靈，寫入 `statusLine` 設定
`/claude-hud:configure`	互動式設定，含預覽功能

設定檔位置

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

claude-hud-statusline

相關技能