hud

name	hud
description	Configure HUD display options (layout, presets, display elements)
role	config-writer
scope	~/.factory/**

HUD Skill

Configure the OMD 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 ~/.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 OR if the HUD script doesn't exist at ~/.factory/hud/omd-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 ~/.factory/hud/omd-hud.mjs 2>/dev/null && echo "EXISTS" || echo "MISSING"

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

# Resolve the active install from Factory's plugin metadata
PLUGIN_DIR=$(node --input-type=module - <<'NODE'
import { readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";

const registries = [
  { path: join(process.cwd(), ".factory/plugins/installed_plugins.json"), scope: "project" },
  { path: join(homedir(), ".factory/plugins/installed_plugins.json"), scope: "user" },
];
for (const registry of registries) {
  try {
    const metadata = JSON.parse(readFileSync(registry.path, "utf-8"));
    const installs = metadata.plugins?.["oh-my-droid@oh-my-droid"] ?? [];
    const install = installs.find((item) => item.scope === registry.scope) ?? installs[0];
    if (install?.installPath) {
      console.log(install.installPath);
      process.exit(0);
    }
  } catch {}
}
console.log("");
NODE
)
if [ -n "$PLUGIN_DIR" ]; then
  test -f "$PLUGIN_DIR/dist/hud/index.js" && 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/ directory contains compiled TypeScript code and is not stored on GitHub. It is normally generated by the package's prepare script during npm install. If lifecycle scripts did not run or the build failed, the HUD bundle will be missing.

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

cd "$PLUGIN_DIR" && 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 from GitHub raw URLs - it doesn't exist there!

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

First, create the directory:

mkdir -p ~/.factory/hud

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

#!/usr/bin/env node
/**
 * OMD HUD - Statusline Script
 * Wrapper that imports from plugin cache or development paths
 */

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

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

  // 1. Resolve the active plugin install from Factory metadata
  const pluginRegistries = [
    {
      path: join(process.cwd(), ".factory/plugins/installed_plugins.json"),
      scope: "project",
    },
    {
      path: join(home, ".factory/plugins/installed_plugins.json"),
      scope: "user",
    },
  ];
  for (const registry of pluginRegistries) {
    if (!existsSync(registry.path)) continue;
    try {
      const pluginsData = JSON.parse(readFileSync(registry.path, "utf-8"));
      const installs = pluginsData.plugins?.["oh-my-droid@oh-my-droid"] ?? [];
      const install = installs.find((item) => item.scope === registry.scope) ?? installs[0];
      pluginCacheDir = install?.installPath || null;
      if (pluginCacheDir) {
        break;
      }
    } catch { /* continue */ }
  }
  if (pluginCacheDir) {
    const pluginPath = join(pluginCacheDir, "dist/hud/index.js");
    if (existsSync(pluginPath)) {
      await import(pathToFileURL(pluginPath).href);
      return;
    }
  }

  // 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, 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:

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

Then set the statusLine field using the resolved path. On Unix it will look like:

{
  "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

Element	Description
[OMD]	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: ~/.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.