hud

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HUD Skill

HUD 技能

Configure the OMC HUD (Heads-Up Display) for the statusline.
Note: All
~/.claude/...
paths in this guide respect
CLAUDE_CONFIG_DIR
when that environment variable is set.
为状态行配置OMC HUD(抬头显示)。
注意:本指南中所有
~/.claude/...
路径在设置了
CLAUDE_CONFIG_DIR
环境变量时,会遵循该变量的配置。

Quick Commands

快速命令

CommandDescription
/oh-my-claudecode:hud
Show current HUD status (auto-setup if needed)
/oh-my-claudecode:hud setup
Install/repair HUD statusline
/oh-my-claudecode:hud minimal
Switch to minimal display
/oh-my-claudecode:hud focused
Switch to focused display (default)
/oh-my-claudecode:hud full
Switch to full display
/oh-my-claudecode:hud status
Show detailed HUD status
命令描述
/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状态

Auto-Setup

自动设置

When you run
/oh-my-claudecode:hud
or
/oh-my-claudecode:hud setup
, the system will automatically:
  1. Check if
    ~/.claude/hud/omc-hud.mjs
    exists
  2. Check if
    statusLine
    is configured in
    ~/.claude/settings.json
  3. If missing, create the HUD wrapper script and configure settings
  4. Report status and prompt to restart Claude Code if changes were made
IMPORTANT: If the argument is
setup
OR if the HUD script doesn't exist at
~/.claude/hud/omc-hud.mjs
, you MUST create the HUD files directly using the instructions below.
当你运行
/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文件。

Setup Instructions (Run These Commands)

设置说明(运行以下命令)

Step 1: Check if setup is needed:
bash
ls ~/.claude/hud/omc-hud.mjs 2>/dev/null && echo "EXISTS" || echo "MISSING"
Step 2: Verify the plugin is installed:
bash
PLUGIN_VERSION=$(ls ~/.claude/plugins/cache/omc/oh-my-claudecode/ 2>/dev/null | sort -V | tail -1)
if [ -n "$PLUGIN_VERSION" ]; then
  ls ~/.claude/plugins/cache/omc/oh-my-claudecode/$PLUGIN_VERSION/dist/hud/index.js 2>/dev/null && echo "READY" || echo "NOT_FOUND - try reinstalling: /plugin install oh-my-claudecode"
else
  echo "Plugin not installed - run: /plugin install oh-my-claudecode"
fi
Step 3: If omc-hud.mjs is MISSING or argument is
setup
, create the HUD directory and script:
First, create the directory:
bash
mkdir -p ~/.claude/hud
Then, use the Write tool to create
~/.claude/hud/omc-hud.mjs
with this exact content:
javascript
#!/usr/bin/env node
/**
 * OMC HUD - Statusline Script
 * Wrapper that imports from plugin cache or development paths
 */

import { existsSync, readdirSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { pathToFileURL } from "node:url";

// Semantic version comparison: returns negative if a < b, positive if a > b, 0 if equal
function semverCompare(a, b) {
  // Use parseInt to handle pre-release suffixes (e.g. "0-beta" -> 0)
  const pa = a.replace(/^v/, "").split(".").map(s => parseInt(s, 10) || 0);
  const pb = b.replace(/^v/, "").split(".").map(s => parseInt(s, 10) || 0);
  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
    const na = pa[i] || 0;
    const nb = pb[i] || 0;
    if (na !== nb) return na - nb;
  }
  // If numeric parts equal, non-pre-release > pre-release
  const aHasPre = /-/.test(a);
  const bHasPre = /-/.test(b);
  if (aHasPre && !bHasPre) return -1;
  if (!aHasPre && bHasPre) return 1;
  return 0;
}

async function main() {
  const home = homedir();
  let pluginCacheDir = null;

  // 1. Try plugin cache first (marketplace: omc, plugin: oh-my-claudecode)
  const pluginCacheBase = join(home, ".claude/plugins/cache/omc/oh-my-claudecode");
  if (existsSync(pluginCacheBase)) {
    try {
      const versions = readdirSync(pluginCacheBase);
      if (versions.length > 0) {
        const latestVersion = versions.sort(semverCompare).reverse()[0];
        pluginCacheDir = join(pluginCacheBase, latestVersion);
        const pluginPath = join(pluginCacheDir, "dist/hud/index.js");
        if (existsSync(pluginPath)) {
          await import(pathToFileURL(pluginPath).href);
          return;
        }
      }
    } catch { /* continue */ }
  }

  // 2. Development paths
  const devPaths = [
    join(home, "Workspace/oh-my-claude-sisyphus/dist/hud/index.js"),
    join(home, "workspace/oh-my-claude-sisyphus/dist/hud/index.js"),
    join(home, "Workspace/oh-my-claudecode/dist/hud/index.js"),
    join(home, "workspace/oh-my-claudecode/dist/hud/index.js"),
  ];

  for (const devPath of devPaths) {
    if (existsSync(devPath)) {
      try {
        await import(pathToFileURL(devPath).href);
        return;
      } catch { /* continue */ }
    }
  }

  // 3. Fallback - HUD not found (provide actionable error message)
  if (pluginCacheDir) {
    console.log(`[OMC] HUD not built. Run: cd "${pluginCacheDir}" && npm install`);
  } else {
    console.log("[OMC] Plugin not found. Run: /oh-my-claudecode:omc-setup");
  }
}

main();
Step 3: Make it executable:
bash
chmod +x ~/.claude/hud/omc-hud.mjs
Step 4: Update settings.json to use the HUD:
Read
~/.claude/settings.json
, then update/add the
statusLine
field.
IMPORTANT: The command must use an absolute path, not
~
, because Windows does not expand
~
in shell commands.
First, determine the correct path:
bash
node -e "const p=require('path').join(require('os').homedir(),'.claude','hud','omc-hud.mjs');console.log(JSON.stringify(p))"
Then set the
statusLine
field using the resolved path. On Unix it will look like:
json
{
  "statusLine": {
    "type": "command",
    "command": "node /home/username/.claude/hud/omc-hud.mjs"
  }
}
On Windows it will look like:
json
{
  "statusLine": {
    "type": "command",
    "command": "node C:\\Users\\username\\.claude\\hud\\omc-hud.mjs"
  }
}
Use the Edit tool to add/update this field while preserving other settings.
Step 5: Clean up old HUD scripts (if any):
bash
rm -f ~/.claude/hud/sisyphus-hud.mjs 2>/dev/null
Step 6: Tell the user to restart Claude Code for changes to take effect.
步骤1:检查是否需要设置
bash
ls ~/.claude/hud/omc-hud.mjs 2>/dev/null && echo "EXISTS" || echo "MISSING"
步骤2:验证插件是否已安装
bash
PLUGIN_VERSION=$(ls ~/.claude/plugins/cache/omc/oh-my-claudecode/ 2>/dev/null | sort -V | tail -1)
if [ -n "$PLUGIN_VERSION" ]; then
  ls ~/.claude/plugins/cache/omc/oh-my-claudecode/$PLUGIN_VERSION/dist/hud/index.js 2>/dev/null && echo "READY" || echo "NOT_FOUND - try reinstalling: /plugin install oh-my-claudecode"
else
  echo "Plugin not installed - run: /plugin install oh-my-claudecode"
fi
步骤3:如果omc-hud.mjs缺失或参数为
setup
,创建HUD目录和脚本
首先,创建目录:
bash
mkdir -p ~/.claude/hud
然后,使用写入工具创建
~/.claude/hud/omc-hud.mjs
,内容如下:
javascript
#!/usr/bin/env node
/**
 * OMC HUD - Statusline Script
 * Wrapper that imports from plugin cache or development paths
 */

import { existsSync, readdirSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { pathToFileURL } from "node:url";

// Semantic version comparison: returns negative if a < b, positive if a > b, 0 if equal
function semverCompare(a, b) {
  // Use parseInt to handle pre-release suffixes (e.g. "0-beta" -> 0)
  const pa = a.replace(/^v/, "").split(".").map(s => parseInt(s, 10) || 0);
  const pb = b.replace(/^v/, "").split(".").map(s => parseInt(s, 10) || 0);
  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
    const na = pa[i] || 0;
    const nb = pb[i] || 0;
    if (na !== nb) return na - nb;
  }
  // If numeric parts equal, non-pre-release > pre-release
  const aHasPre = /-/.test(a);
  const bHasPre = /-/.test(b);
  if (aHasPre && !bHasPre) return -1;
  if (!aHasPre && bHasPre) return 1;
  return 0;
}

async function main() {
  const home = homedir();
  let pluginCacheDir = null;

  // 1. Try plugin cache first (marketplace: omc, plugin: oh-my-claudecode)
  const pluginCacheBase = join(home, ".claude/plugins/cache/omc/oh-my-claudecode");
  if (existsSync(pluginCacheBase)) {
    try {
      const versions = readdirSync(pluginCacheBase);
      if (versions.length > 0) {
        const latestVersion = versions.sort(semverCompare).reverse()[0];
        pluginCacheDir = join(pluginCacheBase, latestVersion);
        const pluginPath = join(pluginCacheDir, "dist/hud/index.js");
        if (existsSync(pluginPath)) {
          await import(pathToFileURL(pluginPath).href);
          return;
        }
      }
    } catch { /* continue */ }
  }

  // 2. Development paths
  const devPaths = [
    join(home, "Workspace/oh-my-claude-sisyphus/dist/hud/index.js"),
    join(home, "workspace/oh-my-claude-sisyphus/dist/hud/index.js"),
    join(home, "Workspace/oh-my-claudecode/dist/hud/index.js"),
    join(home, "workspace/oh-my-claudecode/dist/hud/index.js"),
  ];

  for (const devPath of devPaths) {
    if (existsSync(devPath)) {
      try {
        await import(pathToFileURL(devPath).href);
        return;
      } catch { /* continue */ }
    }
  }

  // 3. Fallback - HUD not found (provide actionable error message)
  if (pluginCacheDir) {
    console.log(`[OMC] HUD not built. Run: cd "${pluginCacheDir}" && npm install`);
  } else {
    console.log("[OMC] Plugin not found. Run: /oh-my-claudecode:omc-setup");
  }
}

main();
步骤3:设置可执行权限
bash
chmod +x ~/.claude/hud/omc-hud.mjs
步骤4:更新settings.json以使用HUD
读取
~/.claude/settings.json
,然后更新或添加
statusLine
字段。
重要提示:命令必须使用绝对路径,不能使用
~
,因为Windows系统不会在shell命令中展开
~
首先,确定正确路径:
bash
node -e "const p=require('path').join(require('os').homedir(),'.claude','hud','omc-hud.mjs');console.log(JSON.stringify(p))"
然后使用解析后的路径设置
statusLine
字段。在Unix系统中如下所示:
json
{
  "statusLine": {
    "type": "command",
    "command": "node /home/username/.claude/hud/omc-hud.mjs"
  }
}
在Windows系统中如下所示:
json
{
  "statusLine": {
    "type": "command",
    "command": "node C:\\Users\\username\\.claude\\hud\\omc-hud.mjs"
  }
}
使用编辑工具添加或更新该字段,同时保留其他设置。
步骤5:清理旧的HUD脚本(如有)
bash
rm -f ~/.claude/hud/sisyphus-hud.mjs 2>/dev/null
步骤6:告知用户重启Claude Code以使更改生效

Display Presets

显示预设

Minimal

极简模式

Shows only the essentials:
[OMC] ralph | ultrawork | todos:2/5
仅显示必要信息:
[OMC] ralph | ultrawork | todos:2/5

Focused (Default)

聚焦模式(默认)

Shows all relevant elements:
[OMC] ralph:3/10 | US-002 | ultrawork skill:planner | ctx:67% | agents:2 | bg:3/5 | todos:2/5
显示所有相关元素:
[OMC] ralph:3/10 | US-002 | ultrawork skill:planner | ctx:67% | agents:2 | bg:3/5 | todos:2/5

Full

完整模式

Shows everything including multi-line agent details:
[OMC] ralph:3/10 | US-002 (2/5) | ultrawork | 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
显示所有信息,包括多行Agent详情:
[OMC] ralph:3/10 | US-002 (2/5) | ultrawork | 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

Multi-Line Agent Display

多行Agent显示

When agents are running, the HUD shows detailed information on separate lines:
  • Tree characters (
    ├─
    ,
    └─
    ) show visual hierarchy
  • Agent code (O, e, s) indicates agent type with model tier color
  • Duration shows how long each agent has been running
  • Description shows what each agent is doing (up to 45 chars)
当Agent运行时,HUD会在单独行显示详细信息:
  • 树形字符
    ├─
    ,
    └─
    )显示视觉层级
  • Agent代码(O, e, s)通过模型层级颜色指示Agent类型
  • 时长显示每个Agent已运行的时间
  • 描述显示每个Agent正在执行的操作(最多45个字符)

Display Elements

显示元素

ElementDescription
[OMC]
Mode identifier
ralph:3/10
Ralph loop iteration/max
US-002
Current PRD story ID
ultrawork
Active mode badge
skill:name
Last activated skill (cyan)
ctx:67%
Context window usage
agents:2
Running subagent count
bg:3/5
Background task slots
todos:2/5
Todo completion
元素描述
[OMC]
模式标识符
ralph:3/10
Ralph循环迭代次数/最大值
US-002
当前PRD需求ID
ultrawork
激活模式徽章
skill:name
最后激活的技能(青色)
ctx:67%
上下文窗口使用率
agents:2
运行中的子Agent数量
bg:3/5
后台任务插槽使用情况
todos:2/5
待办事项完成情况

Color Coding

颜色编码

  • Green: Normal/healthy
  • Yellow: Warning (context >70%, ralph >7)
  • Red: Critical (context >85%, ralph at max)
  • 绿色:正常/健康状态
  • 黄色:警告(上下文使用率>70%,ralph迭代>7)
  • 红色:严重(上下文使用率>85%,ralph达到最大值)

Configuration Location

配置位置

HUD config is stored at:
~/.claude/.omc/hud-config.json
HUD配置存储在:
~/.claude/.omc/hud-config.json

Manual Configuration

手动配置

You can manually edit the config file. Each option can be set individually - any unset values will use defaults.
json
{
  "preset": "focused",
  "elements": {
    "omcLabel": true,
    "ralph": true,
    "prdStory": true,
    "activeSkills": true,
    "lastSkill": true,
    "contextBar": true,
    "agents": true,
    "backgroundTasks": true,
    "todos": true,
    "showCache": true,
    "showCost": true,
    "maxOutputLines": 4
  },
  "thresholds": {
    "contextWarning": 70,
    "contextCritical": 85,
    "ralphWarning": 7
  }
}
你可以手动编辑配置文件。每个选项可单独设置——未设置的选项将使用默认值。
json
{
  "preset": "focused",
  "elements": {
    "omcLabel": true,
    "ralph": true,
    "prdStory": true,
    "activeSkills": true,
    "lastSkill": true,
    "contextBar": true,
    "agents": true,
    "backgroundTasks": true,
    "todos": true,
    "showCache": true,
    "showCost": true,
    "maxOutputLines": 4
  },
  "thresholds": {
    "contextWarning": 70,
    "contextCritical": 85,
    "ralphWarning": 7
  }
}

Troubleshooting

故障排除

If the HUD is not showing:
  1. Run
    /oh-my-claudecode:hud setup
    to auto-install and configure
  2. Restart Claude Code after setup completes
  3. If still not working, run
    /oh-my-claudecode:doctor
    for full diagnostics
Manual verification:
  • HUD script:
    ~/.claude/hud/omc-hud.mjs
  • Settings:
    ~/.claude/settings.json
    should have
    statusLine
    configured

The HUD updates automatically every ~300ms during active sessions.
如果HUD未显示:
  1. 运行
    /oh-my-claudecode:hud setup
    进行自动安装和配置
  2. 设置完成后重启Claude Code
  3. 若仍无法工作,运行
    /oh-my-claudecode:doctor
    进行完整诊断
手动验证:
  • HUD脚本:
    ~/.claude/hud/omc-hud.mjs
  • 设置:
    ~/.claude/settings.json
    中应配置了
    statusLine

在活跃会话中,HUD会每约300ms自动更新一次。