hud

Habilidad HUD

Configura el HUD (Heads-Up Display) de OMC para la barra de estado.

Nota: Todas las rutas ~/.claude/... en esta guía respetan CLAUDE_CONFIG_DIR cuando esa variable de entorno está establecida.

Comandos rápidos

Comando	Descripción
/oh-my-claudecode:hud	Muestra el estado actual del HUD (auto-configuración si es necesario)
/oh-my-claudecode:hud setup	Instala/repara la barra de estado del HUD
/oh-my-claudecode:hud minimal	Cambia a la visualización mínima
/oh-my-claudecode:hud focused	Cambia a la visualización enfocada (por defecto)
/oh-my-claudecode:hud full	Cambia a la visualización completa
/oh-my-claudecode:hud status	Muestra el estado detallado del HUD

Auto-configuración

Cuando ejecutas /oh-my-claudecode:hud o /oh-my-claudecode:hud setup, el sistema automáticamente:

1. Verifica si existe ~/.claude/hud/omc-hud.mjs
2. Verifica si statusLine está configurado en ~/.claude/settings.json
3. Si falta, crea el script contenedor del HUD y configura los ajustes
4. Reporta el estado y solicita reiniciar Claude Code si se hicieron cambios

IMPORTANTE: Si el argumento es setup O si el script del HUD no existe en ~/.claude/hud/omc-hud.mjs, DEBES crear los archivos del HUD directamente usando las instrucciones a continuación.

Instrucciones de configuración (Ejecuta estos comandos)

Paso 1: Verifica si la configuración es necesaria:

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'))?'EXISTE':'FALTA')"

Paso 2: Verifica que el plugin esté instalado:

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 no instalado - ejecuta: /plugin install oh-my-claudecode');process.exit()}const l=v[v.length-1],h=p.join(b,l,'dist','hud','index.js');console.log('Versión:',l);console.log(f.existsSync(h)?'LISTO':'NO_ENCONTRADO - prueba reinstalando: /plugin install oh-my-claudecode')}catch{console.log('Plugin no instalado - ejecuta: /plugin install oh-my-claudecode')}"

Paso 3: Si omc-hud.mjs FALTA o el argumento es setup, instala el contenedor HUD y su dependencia desde la plantilla canónica:

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"

IMPORTANTE: Siempre copia desde la plantilla canónica en scripts/lib/hud-wrapper-template.txt. NO escribas el contenido del contenedor en línea — la plantilla es la fuente única de verdad y está protegida por pruebas de deriva (src/__tests__/hud-wrapper-template-sync.test.ts, src/__tests__/paths-consistency.test.ts).

Paso 4: Hazlo ejecutable (solo Unix, omite en Windows):

node -e "if(process.platform==='win32'){console.log('Omitido (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('Hecho')}"

Paso 5: Actualiza settings.json para usar el HUD:

Lee ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json, luego actualiza/añade el campo statusLine.

IMPORTANTE: No uses ~ en el comando. En Unix, usa $HOME para mantener la ruta portable entre máquinas. En Windows, usa una ruta absoluta porque Windows no expande ~ en comandos de shell.

Si estás en Windows, primero determina la ruta correcta:

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

IMPORTANTE: La ruta del comando DEBE usar barras diagonales en todas las plataformas. Claude Code ejecuta comandos de statusLine mediante bash, que interpreta las barras invertidas como caracteres de escape y rompe la ruta.

Luego establece el campo statusLine. En Unix debe mantenerse portable y verse así:

{
  "statusLine": {
    "type": "command",
    "command": "node ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud/omc-hud.mjs"
  }
}

En Windows la ruta usa barras diagonales (no invertidas):

{
  "statusLine": {
    "type": "command",
    "command": "node C:/Users/username/.claude/hud/omc-hud.mjs"
  }
}

Usa la herramienta Editar para añadir/actualizar este campo mientras conservas otras configuraciones.

Paso 6: Limpia scripts antiguos del HUD (si los hay):

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('Eliminado script heredado omc-hud.js')}else{console.log('No se encontró script heredado')}}catch{}"

Paso 7: Indica al usuario que reinicie Claude Code para que los cambios surtan efecto.

Predefinidos de visualización

Mínimo

Muestra solo lo esencial:

[OMC] ralph | todos:2/5

Enfocado (por defecto)

Muestra todos los elementos relevantes:

[OMC] branch:main | ralph:3/10 | US-002 | skill:planner | ctx:67% | agents:2 | bg:3/5 | todos:2/5

Completo

Muestra todo, incluidos detalles de agentes en varias líneas:

[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   analizando patrones de arquitectura...
├─ e explore     45s   buscando archivos de prueba
└─ s executor     1m   implementando lógica de validación

Visualización multilingüe de agentes

Cuando los agentes están ejecutándose, el HUD muestra información detallada en líneas separadas:

• Caracteres de árbol (├─, └─) muestran jerarquía visual
• Código del agente (O, e, S) indica el tipo de agente con color según el nivel del modelo
• Duración muestra cuánto tiempo lleva ejecutándose cada agente
• Descripción muestra lo que está haciendo cada agente (hasta 45 caracteres)

Elementos de la pantalla

Elemento	Descripción
[OMC]	Identificador de modo
repo:name	Nombre del repositorio Git (cian)
branch:name	Nombre de la rama Git (cian)
ralph:3/10	Iteración/máximo del bucle ralph
US-002	ID de la historia PRD actual
skill:name	Última habilidad activada (cian)
ctx:67%	Uso de la ventana de contexto
agents:2	Número de subagentes en ejecución
bg:3/5	Espacios de tareas en segundo plano
todos:2/5	Completitud de tareas pendientes

Código de colores

• Verde: Normal/saludable
• Amarillo: Advertencia (contexto >70%, ralph >7)
• Rojo: Crítico (contexto >85%, ralph al máximo)

Ubicación de la configuración

La configuración del HUD se almacena en ~/.claude/settings.json bajo la clave omcHud (o tu directorio de configuración personalizado si CLAUDE_CONFIG_DIR está establecido).

Ubicación de configuración heredada (obsoleta): ~/.claude/.omc/hud-config.json

Configuración manual

Puedes editar manualmente el archivo de configuración. Cada opción se puede establecer individualmente; los valores no establecidos usarán los predeterminados.

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

Controla el estilo del icono de badge de conteo de llamadas:

• "auto" (predeterminado): emoji en macOS/Linux, ASCII en Windows/WSL
• "emoji": forzar 🔧 🤖 ⚡
• "ascii": forzar T: A: S:

safeMode

Cuando safeMode es true (predeterminado), el HUD elimina códigos ANSI y usa solo salida ASCII para evitar corrupción de la representación del terminal durante actualizaciones concurrentes. Esto es especialmente importante en Windows y al usar multiplexores de terminal.

Opciones de agentsFormat

• count: agents:2
• codes: agents:Oes (codificados por tipo con mayúsculas/minúsculas según nivel del modelo)
• codes-duration: agents:O(2m)es (códigos con duración)
• detailed: agents:[architect(2m),explore,exec]
• descriptions: O:analizando código | e:buscando (códigos + lo que hacen)
• tasks: [analizando código, buscando...] (solo descripciones)
• multiline: Visualización multilingüe con detalles completos del agente en líneas separadas

Solución de problemas

Si el HUD no se muestra:

1. Ejecuta /oh-my-claudecode:hud setup para instalar y configurar automáticamente
2. Reinicia Claude Code después de que la configuración se complete
3. Si aún no funciona, ejecuta /oh-my-claudecode:omc-doctor para un diagnóstico completo

Migración del formato de cadena heredada: Las versiones anteriores de OMC escribían statusLine como una cadena simple (ej., "~/.claude/hud/omc-hud.mjs"). Claude Code moderno (v2.1+) requiere un formato de objeto. Ejecutar el instalador o /oh-my-claudecode:hud setup migrará automáticamente las cadenas heredadas al formato de objeto correcto:

{
  "statusLine": {
    "type": "command",
    "command": "node ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud/omc-hud.mjs"
  }
}

Compatibilidad con Node 24+: El script contenedor del HUD importa homedir desde node:os (no desde node:path). Si encuentras SyntaxError: The requested module 'path' does not provide an export named 'homedir', vuelve a ejecutar el instalador para regenerar omc-hud.mjs.

Verificación manual:

• Script HUD: ~/.claude/hud/omc-hud.mjs
• Configuración: ~/.claude/settings.json debe tener statusLine configurado como un objeto con los campos type y command

---

El HUD se actualiza automáticamente cada ~300ms durante sesiones activas.