HUD Skill

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

Quick Commands

/hud

/hud setup

/hud minimal

/hud focused

/hud full

/hud status

Auto-Setup

When you run

/hud

/hud setup

1. Check if

   ~/.factory/hud/omd-hud.mjs

   exists
2. Check if

   statusLine

   is configured in

   ~/.factory/settings.json

3. If missing, create the HUD wrapper script and configure settings
4. Report status and prompt to restart Factory Droid if changes were made

IMPORTANT: If the argument is

setup

~/.factory/hud/omd-hud.mjs

Setup Instructions (Run These Commands)

Step 1: Check if setup is needed:

ls ~/.factory/hud/omd-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 ~/.factory/plugins/cache/oh-my-droid/oh-my-droid/ 2>/dev/null | sort -V | tail -1)
if [ -n "$PLUGIN_VERSION" ]; then
  ls ~/.factory/plugins/cache/oh-my-droid/oh-my-droid/$PLUGIN_VERSION/dist/hud/index.js 2>/dev/null && echo "BUILT" || echo "NOT_BUILT"
fi

⚠️ CRITICAL: If NOT_BUILT, the plugin MUST be compiled before the HUD can work!

WHY THIS HAPPENS: The

dist/

prepare

npm install

THE FIX: Run npm install in the plugin directory to build it:

cd ~/.factory/plugins/cache/oh-my-droid/oh-my-droid/$PLUGIN_VERSION && npm install

This will:

1. Install all dependencies
2. Run the

   prepare

   script which executes

   npm run build

3. Generate the

   dist/hud/index.js

   file that the HUD wrapper needs

DO NOT try to download

dist/hud/index.js

Step 3: If omd-hud.mjs is MISSING or argument is

setup

First, create the directory:

mkdir -p ~/.factory/hud

Then, use the Write tool to create

~/.factory/hud/omd-hud.mjs

#!/usr/bin/env node
/**
 * OMD 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) {
  const pa = a.replace(/^v/, "").split(".").map(Number);
  const pb = b.replace(/^v/, "").split(".").map(Number);
  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;
  }
  return 0;
}

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

  // 1. Try plugin cache first (marketplace: omc, plugin: oh-my-droid)
  const pluginCacheBase = join(home, ".factory/plugins/cache/oh-my-droid/oh-my-droid");
  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-droid/dist/hud/index.js"),
    join(home, "workspace/oh-my-droid/dist/hud/index.js"),
    join(home, "Workspace/oh-my-droid/dist/hud/index.js"),
    join(home, "workspace/oh-my-droid/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(`[OMD] HUD not built. Run: cd "${pluginCacheDir}" && npm install`);
  } else {
    console.log("[OMD] Plugin not found. Run: /omd-setup");
  }
}

main();

Step 3: Make it executable:

chmod +x ~/.factory/hud/omd-hud.mjs

Step 4: Update settings.json to use the HUD:

Read

~/.factory/settings.json

statusLine

IMPORTANT: The command must use an absolute path, not

~

~

First, determine the correct path:

node -e "const p=require('path').join(require('os').homedir(),'.factory','hud','omd-hud.mjs');console.log(JSON.stringify(p))"

Then set the

statusLine

{
  "statusLine": {
    "type": "command",
    "command": "node /home/username/.factory/hud/omd-hud.mjs"
  }
}

On Windows it will look like:

{
  "statusLine": {
    "type": "command",
    "command": "node C:\\Users\\username\\.factory\\hud\\omd-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 ~/.factory/hud/sisyphus-hud.mjs 2>/dev/null

Step 6: Tell the user to restart Factory Droid for changes to take effect.

Display Presets

Minimal

Shows only the essentials:

[OMD] ralph | ultrawork | todos:2/5

Focused (Default)

Shows all relevant elements:

[OMD] 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:

[OMD] 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

[OMD]

ralph:3/10

US-002

ultrawork

skill:name

ctx:67%

agents:2

bg:3/5

todos:2/5

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:

~/.factory/.omd/hud-config.json

Manual Configuration

You can manually edit the config file. Each option can be set individually - any unset values will use defaults.

{
  "preset": "focused",
  "elements": {
    "omdLabel": 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

   /hud setup

   to auto-install and configure
2. Restart Factory Droid after setup completes
3. If still not working, run

   /doctor

   for full diagnostics

Manual verification:

• HUD script:

  ~/.factory/hud/omd-hud.mjs

• Settings:

  ~/.factory/settings.json

  should have

  statusLine

  configured

The HUD updates automatically every ~300ms during active sessions.