HUD 技能

HUD 技能 是做什麼的？

設定 OMC HUD（抬頭顯示器）的狀態列。

注意：本指南中所有 ~/.claude/... 路徑都會在設定 CLAUDE_CONFIG_DIR 環境變數時使用該變數。

快速命令

命令	說明
/oh-my-claudecode:hud	顯示目前 HUD 狀態（必要時自動設定）
/oh-my-claudecode:hud setup	安裝／修復 HUD 狀態列
/oh-my-claudecode:hud minimal	切換至精簡顯示
/oh-my-claudecode:hud focused	切換至聚焦顯示（預設）
/oh-my-claudecode:hud full	切換至完整顯示
/oh-my-claudecode:hud status	顯示詳細的 HUD 狀態

自動設定

當你執行 /oh-my-claudecode:hud 或 /oh-my-claudecode:hud setup 時，系統將自動：

1. 檢查 ~/.claude/hud/omc-hud.mjs 是否存在
2. 檢查 ~/.claude/settings.json 中是否已設定 statusLine
3. 若缺少，則建立 HUD 包裝腳本並設定相關配置
4. 回報狀態，並提示在變更後重新啟動 Claude Code

重要：如果參數是 setup，或者 HUD 腳本不存在於 ~/.claude/hud/omc-hud.mjs，則你必須依照下列指示直接建立 HUD 檔案。

設定指示（執行這些命令）

步驟 1： 檢查是否需要設定：

node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude');console.log(f.existsSync(p.join(d,'hud','omc-hud.mjs'))?'EXISTS':'MISSING')"

步驟 2： 確認外掛已安裝：

node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude'),b=p.join(d,'plugins','cache','omc','oh-my-claudecode');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));if(v.length===0){console.log('外掛尚未安裝 - 執行：/plugin install oh-my-claudecode');process.exit()}const l=v[v.length-1],h=p.join(b,l,'dist','hud','index.js');console.log('版本：',l);console.log(f.existsSync(h)?'READY':'NOT_FOUND - 請嘗試重新安裝：/plugin install oh-my-claudecode')}catch{console.log('外掛尚未安裝 - 執行：/plugin install oh-my-claudecode')}"

步驟 3： 如果 omc-hud.mjs 遺失或參數為 setup，請從規範模板安裝 HUD 包裝腳本及其相依模組：

HUD_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud"
mkdir -p "$HUD_DIR/lib"
cp "${CLAUDE_PLUGIN_ROOT}/scripts/lib/hud-wrapper-template.txt" "$HUD_DIR/omc-hud.mjs"
cp "${CLAUDE_PLUGIN_ROOT}/scripts/lib/config-dir.mjs" "$HUD_DIR/lib/config-dir.mjs"

重要： 務必從 scripts/lib/hud-wrapper-template.txt 這個規範模板複製。請不要內嵌包裝內容——模板是唯一可靠的來源，並受漂移測試（src/__tests__/hud-wrapper-template-sync.test.ts、src/__tests__/paths-consistency.test.ts）保護。

步驟 4： 使其可執行（僅限 Unix，Windows 請跳過）：

node -e "if(process.platform==='win32'){console.log('已跳過 (Windows)')}else{require('fs').chmodSync(require('path').join(process.env.CLAUDE_CONFIG_DIR||require('path').join(require('os').homedir(),'.claude'),'hud','omc-hud.mjs'),0o755);console.log('完成')}"

步驟 5： 更新 settings.json 以使用 HUD：

讀取 ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json，然後更新／新增 statusLine 欄位。

重要： 不要在命令中使用 ~。在 Unix 上請用 $HOME 以保持路徑在不同機器間的可移植性。在 Windows 上請使用絕對路徑，因為 Windows 在 shell 命令中不會展開 ~。

如果你正在使用 Windows，請先確定正確的路徑：

node -e "const p=require('path').join(require('os').homedir(),'.claude','hud','omc-hud.mjs').split(require('path').sep).join('/');console.log(JSON.stringify(p))"

重要： 命令路徑必須在所有平台上都使用正斜線。Claude Code 透過 bash 執行 statusLine 命令，而反斜線會被解讀為跳脫字元，導致路徑錯誤。

接著設定 statusLine 欄位。在 Unix 上它應保持可移植，看起來像這樣：

{
  "statusLine": {
    "type": "command",
    "command": "node ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud/omc-hud.mjs"
  }
}

在 Windows 上路徑使用正斜線（而非反斜線）：

{
  "statusLine": {
    "type": "command",
    "command": "node C:/Users/username/.claude/hud/omc-hud.mjs"
  }
}

使用編輯工具新增／更新此欄位，同時保留其他設定。

步驟 6： 清理舊的 HUD 腳本（如有）：

node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude'),t=p.join(d,'hud','omc-hud.js');try{if(f.existsSync(t)){f.unlinkSync(t);console.log('已移除舊版 omc-hud.js')}else{console.log('未找到舊版腳本')}}catch{}"

步驟 7： 告知使用者重新啟動 Claude Code 以使變更生效。

顯示預設集

精簡

僅顯示必要資訊：

[OMC] ralph | todos:2/5

聚焦（預設）

顯示所有相關元素：

[OMC] branch:main | ralph:3/10 | US-002 | skill:planner | ctx:67% | agents:2 | bg:3/5 | todos:2/5

完整

顯示所有內容，包括多行代理詳細資訊：

[OMC] repo:oh-my-claudecode branch:main | ralph:3/10 | US-002 (2/5) | ctx:[████░░]67% | agents:3 | bg:3/5 | todos:2/5
├─ O architect    2m   analyzing architecture patterns...
├─ e explore     45s   searching for test files
└─ s executor     1m   implementing validation logic

多行代理顯示

當代理正在執行時，HUD 會在獨立行上顯示詳細資訊：

• 樹狀字元（├─、└─）顯示視覺階層
• 代理代碼（O、e、s）表示代理類型，並附帶模型層級色彩
• 持續時間顯示每個代理已執行多久
• 描述顯示每個代理正在做什麼（最多 45 個字元）

顯示元素

元素	說明
[OMC]	模式識別碼
repo:name	Git 儲存庫名稱（青色）
branch:name	Git 分支名稱（青色）
ralph:3/10	Ralph 迴圈迭代次數／上限
US-002	目前 PRD 故事 ID
skill:name	最後啟動的技能（青色）
ctx:67%	上下文視窗使用率
agents:2	正在執行的子代理數量
bg:3/5	背景任務槽位
todos:2/5	待辦事項完成進度

色彩編碼

• 綠色：正常／健康
• 黃色：警告（上下文 >70%、Ralph >7）
• 紅色：危急（上下文 >85%、Ralph 達到上限）

設定位置

HUD 設定儲存在 ~/.claude/settings.json 的 omcHud 鍵下（或自訂目錄，若已設定 CLAUDE_CONFIG_DIR）。

舊版設定位置（已棄用）：~/.claude/.omc/hud-config.json

手動設定

你可以手動編輯設定檔。每個選項可獨立設定——未設定的值會使用預設值。

{
  "preset": "focused",
  "elements": {
    "omcLabel": true,
    "updateNotification": true,
    "ralph": true,
    "autopilot": true,
    "prdStory": true,
    "activeSkills": true,
    "lastSkill": true,
    "contextBar": true,
    "agents": true,
    "agentsFormat": "multiline",
    "backgroundTasks": true,
    "todos": true,
    "thinking": true,
    "thinkingFormat": "text",
    "permissionStatus": false,
    "apiKeySource": false,
    "profile": true,
    "promptTime": true,
    "sessionHealth": true,
    "useBars": true,
    "showCallCounts": true,
    "callCountsFormat": "auto",
    "safeMode": true,
    "maxOutputLines": 4
  },
  "thresholds": {
    "contextWarning": 70,
    "contextCompactSuggestion": 80,
    "contextCritical": 85,
    "ralphWarning": 7
  },
  "staleTaskThresholdMinutes": 30,
  "contextLimitWarning": {
    "threshold": 80,
    "autoCompact": false
  }
}

callCountsFormat

控制呼叫計數徽章圖示樣式：

• "auto"（預設）：macOS/Linux 使用表情符號，Windows/WSL 使用 ASCII
• "emoji"：強制使用 🔧 🤖 ⚡
• "ascii"：強制使用 T: A: S:

safeMode

當 safeMode 為 true（預設）時，HUD 會移除 ANSI 碼，僅使用 ASCII 輸出，以防止並行更新期間終端機渲染異常。這在 Windows 及使用終端機多路複用器時尤其重要。

agentsFormat 選項

• count：agents:2
• codes：agents:Oes（類型編碼，附帶模型層級大小寫）
• codes-duration：agents:O(2m)es（代碼加持續時間）
• detailed：agents:[architect(2m),explore,exec]
• descriptions：O:analyzing code | e:searching（代碼加上正在做的事）
• tasks：[analyzing code, searching...]（僅描述）
• multiline：多行顯示，每個代理的詳細資訊顯示在獨立行上

疑難排解

如果 HUD 沒有顯示：

1. 執行 /oh-my-claudecode:hud setup 以自動安裝與設定
2. 設定完成後重新啟動 Claude Code
3. 若仍無法運作，執行 /oh-my-claudecode:omc-doctor 進行完整診斷

舊版字串格式遷移： 舊版 OMC 將 statusLine 寫為純字串（例如 "~/.claude/hud/omc-hud.mjs"）。現代 Claude Code（v2.1+）需要物件格式。執行安裝程式或 /oh-my-claudecode:hud setup 會自動將舊版字串遷移為正確的物件格式：

{
  "statusLine": {
    "type": "command",
    "command": "node ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud/omc-hud.mjs"
  }
}

Node 24+ 相容性： HUD 包裝腳本從 node:os（而非 node:path）匯入 homedir。若遇到 SyntaxError: The requested module 'path' does not provide an export named 'homedir'，請重新執行安裝程式以重新產生 omc-hud.mjs。

手動驗證：

• HUD 腳本：~/.claude/hud/omc-hud.mjs
• 設定：~/.claude/settings.json 應具有設定為包含 type 和 command 欄位之物件的 statusLine

---

HUD 在活動工作階段中會自動每隔約 300 毫秒更新一次。