hud

HUD Skill

Configure the OMC HUD (Heads-Up Display) for the statusline.

Quick Commands

Command	Description
/hud	Show current HUD status (auto-setup if needed)
/hud setup	Install/repair HUD statusline
/hud minimal	Switch to minimal display
/hud focused	Switch to focused display (default)
/hud full	Switch to full display
/hud status	Show detailed HUD status

Auto-Setup

When you run /hud or /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.

Setup Instructions (Run These Commands)

Step 1: Check if setup is needed:

ls ~/.claude/hud/omc-hud.mjs 2>/dev/null && echo "EXISTS" || echo "MISSING"

Step 2: Check if the plugin is built (CRITICAL - common issue!):

# Find the latest version and check if dist/hud/index.js exists
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 "BUILT" || echo "NOT_BUILT"
fi

If NOT_BUILT, the plugin needs to be compiled. Run:

cd ~/.claude/plugins/cache/omc/oh-my-claudecode/$PLUGIN_VERSION && npm install

This will install dependencies and build the TypeScript code automatically (via the prepare script).

Step 3: If omc-hud.mjs is MISSING or argument is setup, create the HUD directory and script:

First, create the directory:

mkdir -p ~/.claude/hud

Then, use the Write tool to create ~/.claude/hud/omc-hud.mjs with this exact content:

#!/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";

async function main() {
  const home = homedir();

  // 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().reverse()[0];
        const pluginPath = join(pluginCacheBase, latestVersion, "dist/hud/index.js");
        if (existsSync(pluginPath)) {
          await import(pluginPath);
          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(devPath);
        return;
      } catch { /* continue */ }
    }
  }

  // 3. Fallback
  console.log("[OMC] run /omc-setup to install properly");
}

main();

Step 3: Make it executable:

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:

{
  "statusLine": {
    "type": "command",
    "command": "node ~/.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):

rm -f ~/.claude/hud/sisyphus-hud.mjs 2>/dev/null

Step 6: Tell the user to restart Claude Code for changes to take effect.

Display Presets

Minimal

Shows only the essentials:

[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

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

Multi-Line Agent Display

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)

Display Elements

Element	Description
[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

Color Coding

• Green: Normal/healthy
• Yellow: Warning (context >70%, ralph >7)
• Red: Critical (context >85%, ralph at max)

Configuration Location

HUD config is stored at: ~/.claude/.omc/hud-config.json

Manual Configuration

You can manually edit the config file:

{
  "preset": "focused",
  "elements": {
    "omcLabel": true,
    "ralph": true,
    "prdStory": true,
    "activeSkills": true,
    "lastSkill": true,
    "contextBar": true,
    "agents": true,
    "backgroundTasks": true,
    "todos": true
  },
  "thresholds": {
    "contextWarning": 70,
    "contextCritical": 85,
    "ralphWarning": 7
  }
}

Troubleshooting

If the HUD is not showing:

1. Run /hud setup to auto-install and configure
2. Restart Claude Code after setup completes
3. If still not working, run /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.