hud

Compétence HUD

Configurer l'HUD (Heads-Up Display) d'OMC pour la barre d'état.

Remarque : Tous les chemins ~/.claude/... dans ce guide respectent CLAUDE_CONFIG_DIR lorsque cette variable d'environnement est définie.

Commandes rapides

Commande	Description
/oh-my-claudecode:hud	Afficher l'état actuel de l'HUD (configuration auto si nécessaire)
/oh-my-claudecode:hud setup	Installer/réparer la barre d'état HUD
/oh-my-claudecode:hud minimal	Passer à l'affichage minimal
/oh-my-claudecode:hud focused	Passer à l'affichage ciblé (par défaut)
/oh-my-claudecode:hud full	Passer à l'affichage complet
/oh-my-claudecode:hud status	Afficher l'état détaillé de l'HUD

Configuration automatique

Lorsque vous exécutez /oh-my-claudecode:hud ou /oh-my-claudecode:hud setup, le système va automatiquement :

1. Vérifier si ~/.claude/hud/omc-hud.mjs existe
2. Vérifier si statusLine est configuré dans ~/.claude/settings.json
3. Si manquant, créer le script wrapper HUD et configurer les paramètres
4. Signaler l'état et inviter à redémarrer Claude Code si des modifications ont été apportées

IMPORTANT : Si l'argument est setup OU si le script HUD n'existe pas dans ~/.claude/hud/omc-hud.mjs, vous DEVEZ créer les fichiers HUD directement en utilisant les instructions ci-dessous.

Instructions d'installation (exécutez ces commandes)

Étape 1 : Vérifier si l'installation est nécessaire :

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

Étape 2 : Vérifier que le plugin est installé :

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 non installé - exécutez : /plugin install oh-my-claudecode');process.exit()}const l=v[v.length-1],h=p.join(b,l,'dist','hud','index.js');console.log('Version :',l);console.log(f.existsSync(h)?'PRÊT':'INTROUVABLE - essayez de réinstaller : /plugin install oh-my-claudecode')}catch{console.log('Plugin non installé - exécutez : /plugin install oh-my-claudecode')}"

Étape 3 : Si omc-hud.mjs est MANQUANT ou si l'argument est setup, installez le wrapper HUD et sa dépendance à partir du modèle canonique :

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"

IMPORTANT : Copiez toujours depuis le modèle canonique scripts/lib/hud-wrapper-template.txt. N'écrivez PAS le contenu du wrapper en ligne — le modèle est la source unique de vérité et est protégé par des tests de dérive (src/__tests__/hud-wrapper-template-sync.test.ts, src/__tests__/paths-consistency.test.ts).

Étape 4 : Rendez-le exécutable (Unix uniquement, sautez sur Windows) :

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

Étape 5 : Mettez à jour settings.json pour utiliser l'HUD :

Lisez ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json, puis mettez à jour/ajoutez le champ statusLine.

IMPORTANT : N'utilisez pas ~ dans la commande. Sur Unix, utilisez $HOME pour garder le chemin portable entre les machines. Sur Windows, utilisez un chemin absolu car Windows ne développe pas ~ dans les commandes shell.

Si vous êtes sur Windows, déterminez d'abord le chemin correct :

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

IMPORTANT : Le chemin de la commande DOIT utiliser des barres obliques sur toutes les plateformes. Claude Code exécute les commandes statusLine via bash, qui interprète les barres obliques inverses comme des caractères d'échappement et brise le chemin.

Définissez ensuite le champ statusLine. Sur Unix, il doit rester portable et ressembler à :

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

Sur Windows, le chemin utilise des barres obliques (pas de barres obliques inverses) :

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

Utilisez l'outil Éditer pour ajouter/mettre à jour ce champ en préservant les autres paramètres.

Étape 6 : Nettoyez les anciens scripts HUD (le cas échéant) :

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('Ancien omc-hud.js supprimé')}else{console.log('Aucun ancien script trouvé')}}catch{}"

Étape 7 : Dites à l'utilisateur de redémarrer Claude Code pour que les changements prennent effet.

Préréglages d'affichage

Minimal

Affiche uniquement l'essentiel :

[OMC] ralph | todos:2/5

Ciblé (par défaut)

Affiche tous les éléments pertinents :

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

Complet

Affiche tout, y compris les détails multi-lignes des agents :

[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 architecte    2m   analyse des modèles d'architecture...
├─ e explorateur  45s   recherche de fichiers de test
└─ s exécuteur     1m   implémente la logique de validation

Affichage multi-lignes des agents

Lorsque des agents sont en cours d'exécution, l'HUD affiche des informations détaillées sur des lignes séparées :

• Caractères d'arborescence (├─, └─) montrent la hiérarchie visuelle
• Code agent (O, e, s) indique le type d'agent avec la couleur du niveau de modèle
• Durée indique depuis combien de temps chaque agent est en cours d'exécution
• Description montre ce que chaque agent fait (jusqu'à 45 caractères)

Éléments d'affichage

Élément	Description
[OMC]	Identifiant du mode
repo:nom	Nom du dépôt Git (cyan)
branch:nom	Nom de la branche Git (cyan)
ralph:3/10	Itération Ralph max/courante
US-002	ID de l'histoire PRD actuelle
skill:nom	Dernière compétence activée (cyan)
ctx:67%	Utilisation de la fenêtre de contexte
agents:2	Nombre de sous-agents en cours
bg:3/5	Emplacements de tâches d'arrière-plan
todos:2/5	Achèvement des tâches

Code couleur

• Vert : Normal/en bon état
• Jaune : Avertissement (contexte >70 %, ralph >7)
• Rouge : Critique (contexte >85 %, ralph au maximum)

Emplacement de la configuration

La configuration HUD est stockée dans ~/.claude/settings.json sous la clé omcHud (ou votre répertoire de configuration personnalisé si CLAUDE_CONFIG_DIR est défini).

Emplacement de l'ancienne configuration (obsolète) : ~/.claude/.omc/hud-config.json

Configuration manuelle

Vous pouvez modifier manuellement le fichier de configuration. Chaque option peut être définie individuellement — les valeurs non définies utiliseront les valeurs par défaut.

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

Contrôle le style de l'icône du badge de comptage d'appels :

• "auto" (par défaut) : emoji sur macOS/Linux, ASCII sur Windows/WSL
• "emoji" : force 🔧 🤖 ⚡
• "ascii" : force T: A: S:

safeMode

Lorsque safeMode est true (par défaut), l'HUD supprime les codes ANSI et utilise une sortie ASCII uniquement pour éviter la corruption du rendu du terminal lors des mises à jour simultanées. Ceci est particulièrement important sur Windows et lors de l'utilisation de multiplexeurs de terminal.

Options agentsFormat

• count : agents:2
• codes : agents:Oes (codé par type avec casse du niveau de modèle)
• codes-duration : agents:O(2m)es (codes avec durée)
• detailed : agents:[architecte(2m),explorateur,exécuteur]
• descriptions : O:analyse du code | e:recherche (codes + ce qu'ils font)
• tasks : [analyse du code, recherche...] (juste les descriptions)
• multiline : Affichage multi-lignes avec détails complets des agents sur des lignes séparées

Dépannage

Si l'HUD ne s'affiche pas :

1. Exécutez /oh-my-claudecode:hud setup pour installer et configurer automatiquement
2. Redémarrez Claude Code après la fin de l'installation
3. Si cela ne fonctionne toujours pas, exécutez /oh-my-claudecode:omc-doctor pour un diagnostic complet

Migration du format chaîne hérité : Les anciennes versions d'OMC écrivaient statusLine comme une simple chaîne (ex. "~/.claude/hud/omc-hud.mjs"). Les versions modernes de Claude Code (v2.1+) nécessitent un format objet. Exécuter l'installateur ou /oh-my-claudecode:hud setup migrera automatiquement les chaînes héritées vers le format objet correct :

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

Compatibilité Node 24+ : Le script wrapper HUD importe homedir depuis node:os (pas node:path). Si vous rencontrez SyntaxError: The requested module 'path' does not provide an export named 'homedir', réexécutez l'installateur pour régénérer omc-hud.mjs.

Vérification manuelle :

• Script HUD : ~/.claude/hud/omc-hud.mjs
• Paramètres : ~/.claude/settings.json doit avoir statusLine configuré comme un objet avec les champs type et command

---

L'HUD se met à jour automatiquement toutes les ~300 ms pendant les sessions actives.