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 not installed - run: /plugin install oh-my-claudecode');process.exit()}const l=v[v.length-1],h=p.join(b,l,'dist','hud','index.js');console.log('Version:',l);console.log(f.existsSync(h)?'READY':'NOT_FOUND - try reinstalling: /plugin install oh-my-claudecode')}catch{console.log('Plugin not installed - run: /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('Skipped (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('Done')}"

步骤 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 命令，bash 会将反斜杠解释为转义字符，从而导致路径错误。

然后设置 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('Removed legacy omc-hud.js')}else{console.log('No legacy script found')}}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 上使用 emoji，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 应配置 statusLine 为包含 type 和 command 字段的对象

---

在有活动会话期间，HUD 大约每 300ms 自动更新一次。