hud

Skill HUD

Configure o HUD (Heads-Up Display) do OMC para a linha de status.

Nota: Todos os caminhos ~/.claude/... neste guia respeitam CLAUDE_CONFIG_DIR quando essa variável de ambiente está definida.

Comandos Rápidos

Comando	Descrição
/oh-my-claudecode:hud	Mostrar status atual do HUD (configuração automática se necessário)
/oh-my-claudecode:hud setup	Instalar/reparar a linha de status do HUD
/oh-my-claudecode:hud minimal	Alternar para exibição mínima
/oh-my-claudecode:hud focused	Alternar para exibição focada (padrão)
/oh-my-claudecode:hud full	Alternar para exibição completa
/oh-my-claudecode:hud status	Mostrar status detalhado do HUD

Configuração Automática

Quando você executa /oh-my-claudecode:hud ou /oh-my-claudecode:hud setup, o sistema irá automaticamente:

1. Verificar se ~/.claude/hud/omc-hud.mjs existe
2. Verificar se statusLine está configurado em ~/.claude/settings.json
3. Se estiver faltando, criar o script wrapper do HUD e configurar as definições
4. Reportar o status e solicitar a reinicialização do Claude Code se alterações foram feitas

IMPORTANTE: Se o argumento for setup OU se o script do HUD não existir em ~/.claude/hud/omc-hud.mjs, você DEVE criar os arquivos do HUD diretamente usando as instruções abaixo.

Instruções de Configuração (Execute Estes Comandos)

Passo 1: Verificar se a configuração é necessária:

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'))?'EXISTS':'MISSING')"

Passo 2: Verificar se o 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 não instalado - execute: /plugin install oh-my-claudecode');process.exit()}const l=v[v.length-1],h=p.join(b,l,'dist','hud','index.js');console.log('Versão:',l);console.log(f.existsSync(h)?'PRONTO':'NÃO_ENCONTRADO - tente reinstalar: /plugin install oh-my-claudecode')}catch{console.log('Plugin não instalado - execute: /plugin install oh-my-claudecode')}"

Passo 3: Se omc-hud.mjs estiver AUSENTE ou o argumento for setup, instale o wrapper HUD e sua dependência a partir do modelo canônico:

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: Sempre copie do modelo canônico em scripts/lib/hud-wrapper-template.txt. NÃO escreva o conteúdo do wrapper inline — o modelo é a fonte única da verdade e é protegido por testes de derivação (src/__tests__/hud-wrapper-template-sync.test.ts, src/__tests__/paths-consistency.test.ts).

Passo 4: Torná-lo executável (apenas Unix, pular no Windows):

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

Passo 5: Atualizar settings.json para usar o HUD:

Leia ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json, em seguida atualize/adicione o campo statusLine.

IMPORTANTE: Não use ~ no comando. No Unix, use $HOME para manter o caminho portável entre máquinas. No Windows, use um caminho absoluto porque o Windows não expande ~ em comandos shell.

Se você estiver no Windows, primeiro determine o caminho correto:

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: O caminho do comando DEVE usar barras normais em todas as plataformas. O Claude Code executa comandos statusLine via bash, que interpreta barras invertidas como caracteres de escape e quebra o caminho.

Em seguida, defina o campo statusLine. No Unix, deve permanecer portável e parecer com:

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

No Windows, o caminho usa barras normais (não invertidas):

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

Use a ferramenta Edit para adicionar/atualizar este campo preservando outras configurações.

Passo 6: Limpar scripts HUD antigos (se houver):

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('Removido script legado omc-hud.js')}else{console.log('Nenhum script legado encontrado')}}catch{}"

Passo 7: Informe ao usuário para reiniciar o Claude Code para que as alterações entrem em vigor.

Predefinições de Exibição

Mínima

Mostra apenas o essencial:

[OMC] ralph | todos:2/5

Focada (Padrão)

Mostra todos os elementos relevantes:

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

Completa

Mostra tudo, incluindo detalhes de agente em várias linhas:

[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   analisando padrões de arquitetura...
├─ e explore     45s   pesquisando arquivos de teste
└─ s executor     1m   implementando lógica de validação

Exibição de Agente em Múltiplas Linhas

Quando agentes estão em execução, o HUD mostra informações detalhadas em linhas separadas:

• Caracteres de árvore (├─, └─) mostram hierarquia visual
• Código do agente (O, e, s) indica o tipo de agente com cor do nível do modelo
• Duração mostra há quanto tempo cada agente está em execução
• Descrição mostra o que cada agente está fazendo (até 45 caracteres)

Elementos de Exibição

Elemento	Descrição
[OMC]	Identificador de modo
repo:nome	Nome do repositório Git (ciano)
branch:nome	Nome do branch Git (ciano)
ralph:3/10	Iteração/máximo do loop Ralph
US-002	ID da história PRD atual
skill:nome	Última skill ativada (ciano)
ctx:67%	Uso da janela de contexto
agents:2	Contagem de subagentes em execução
bg:3/5	Slots de tarefas em segundo plano
todos:2/5	Conclusão de tarefas

Codificação de Cores

• Verde: Normal/saudável
• Amarelo: Aviso (contexto >70%, ralph >7)
• Vermelho: Crítico (contexto >85%, ralph no máximo)

Localização da Configuração

A configuração do HUD é armazenada em ~/.claude/settings.json sob a chave omcHud (ou no diretório de configuração personalizado se CLAUDE_CONFIG_DIR estiver definido).

Localização de configuração legada (obsoleta): ~/.claude/.omc/hud-config.json

Configuração Manual

Você pode editar manualmente o arquivo de configuração. Cada opção pode ser definida individualmente — quaisquer valores não definidos usarão os padrões.

{
  "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 o estilo do ícone do contador de chamadas:

• "auto" (padrão): emoji no macOS/Linux, ASCII no Windows/WSL
• "emoji": forçar 🔧 🤖 ⚡
• "ascii": forçar T: A: S:

safeMode

Quando safeMode é true (padrão), o HUD remove códigos ANSI e usa apenas saída ASCII para evitar corrupção de renderização do terminal durante atualizações simultâneas. Isso é especialmente importante no Windows e ao usar multiplexadores de terminal.

Opções de agentsFormat

• count: agents:2
• codes: agents:Oes (codificado por tipo com capitalização do nível do modelo)
• codes-duration: agents:O(2m)es (códigos com duração)
• detailed: agents:[architect(2m),explore,exec]
• descriptions: O:analisando código | e:pesquisando (códigos + o que estão fazendo)
• tasks: [analisando código, pesquisando...] (apenas descrições)
• multiline: Exibição em várias linhas com detalhes completos do agente em linhas separadas

Solução de Problemas

Se o HUD não estiver aparecendo:

1. Execute /oh-my-claudecode:hud setup para instalar e configurar automaticamente
2. Reinicie o Claude Code após a conclusão da configuração
3. Se ainda não funcionar, execute /oh-my-claudecode:omc-doctor para diagnóstico completo

Migração de formato de string legada: Versões mais antigas do OMC escreviam statusLine como uma string simples (ex.: "~/.claude/hud/omc-hud.mjs"). O Claude Code moderno (v2.1+) requer um formato de objeto. Executar o instalador ou /oh-my-claudecode:hud setup irá migrar automaticamente strings legadas para o formato de objeto correto:

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

Compatibilidade com Node 24+: O script wrapper do HUD importa homedir de node:os (não de node:path). Se você encontrar SyntaxError: The requested module 'path' does not provide an export named 'homedir', execute o instalador novamente para regenerar omc-hud.mjs.

Verificação manual:

• Script HUD: ~/.claude/hud/omc-hud.mjs
• Configurações: ~/.claude/settings.json deve ter statusLine configurado como um objeto com os campos type e command

---

O HUD é atualizado automaticamente a cada ~300ms durante sessões ativas.