hud
Configure HUD display options (layout, presets, display elements)
>_
Quick Installnpxskills add yeachan-heo/oh-my-claudecode--skill hudInstructions
Loading…
Tags & Topics
agentic-codingai-agentsclaudeclaude-codeoh-my-opencodeopencode
Configure HUD display options (layout, presets, display elements)
npxskills add yeachan-heo/oh-my-claudecode--skill hudLoading…
Configure the OMC HUD (Heads-Up Display) for the statusline.
Note: All ~/.claude/... paths in this guide respect CLAUDE_CONFIG_DIR when that environment variable is set.
| Command | Description |
|---|---|
/oh-my-claudecode:hud | Show current HUD status (auto-setup if needed) |
/oh-my-claudecode:hud setup | Install/repair HUD statusline |
/oh-my-claudecode:hud minimal | Switch to minimal display |
/oh-my-claudecode:hud focused |
| Switch to focused display (default) |
/oh-my-claudecode:hud full | Switch to full display |
/oh-my-claudecode:hud status | Show detailed HUD status |
When you run /oh-my-claudecode:hud or /oh-my-claudecode:hud setup, the system will automatically:
~/.claude/hud/omc-hud.mjs existsstatusLine is configured in ~/.claude/settings.jsonIMPORTANT: If the argument is setup OR if the HUD script doesn't exist at ~/.claude/hud/omc-hud.mjs, you MUST create the HUD files directly using the instructions below.
Step 1: Check if setup is needed:
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')"
Step 2: Verify the plugin is installed:
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 not installed - run: /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)?'READY':'NOT_FOUND - try reinstalling: /plugin install oh-my-claudecode')}catch{console.log('Plugin not installed - run: /plugin install oh-my-claudecode')}"
Step 3: If omc-hud.mjs is MISSING or argument is setup, install the HUD wrapper and its dependency from the canonical template:
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: Always copy from the canonical template at scripts/lib/hud-wrapper-template.txt. Do NOT write the wrapper content inline — the template is the single source of truth and is guarded by drift tests (src/__tests__/hud-wrapper-template-sync.test.ts, src/__tests__/paths-consistency.test.ts).
Step 4: Make it executable (Unix only, skip on Windows):
node -e "if(process.platform==='win32'){console.log('Skipped (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('Done')}"
Step 5: Update settings.json to use the HUD:
Read ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json, then update/add the statusLine field.
IMPORTANT: Do not use ~ in the command. On Unix, use $HOME to keep the path portable across machines. On Windows, use an absolute path because Windows does not expand ~ in shell commands.
If you are on Windows, first determine the correct path:
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: The command path MUST use forward slashes on all platforms. Claude Code executes statusLine commands via bash, which interprets backslashes as escape characters and breaks the path.
Then set the statusLine field. On Unix it should stay portable and look like:
{
"statusLine": {
"type": "command",
"command": "node ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud/omc-hud.mjs"
}
}
On Windows the path uses forward slashes (not backslashes):
{
"statusLine": {
"type": "command",
"command": "node C:/Users/username/.claude/hud/omc-hud.mjs"
}
}
Use the Edit tool to add/update this field while preserving other settings.
Step 6: Clean up old HUD scripts (if any):
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('Removed legacy omc-hud.js')}else{console.log('No legacy script found')}}catch{}"
Step 7: Tell the user to restart Claude Code for changes to take effect.
Shows only the essentials:
[OMC] ralph | ultrawork | todos:2/5
Shows all relevant elements:
[OMC] branch:main | ralph:3/10 | US-002 | ultrawork skill:planner | ctx:67% | agents:2 | bg:3/5 | todos:2/5
Shows everything including multi-line agent details:
[OMC] repo:oh-my-claudecode branch:main | 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
When agents are running, the HUD shows detailed information on separate lines:
├─, └─) show visual hierarchy| Element | Description |
|---|---|
[OMC] | Mode identifier |
repo:name | Git repository name (cyan) |
branch:name | Git branch name (cyan) |
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 |
HUD config is stored in ~/.claude/settings.json under the omcHud key (or your custom config directory if CLAUDE_CONFIG_DIR is set).
Legacy config location (deprecated): ~/.claude/.omc/hud-config.json
You can manually edit the config file. Each option can be set individually - any unset values will use defaults.
{
"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
}
}
Controls the call-count badge icon style:
"auto" (default): emoji on macOS/Linux, ASCII on Windows/WSL"emoji": force 🔧 🤖 ⚡"ascii": force T: A: S:When safeMode is true (default), the HUD strips ANSI codes and uses ASCII-only output to prevent terminal rendering corruption during concurrent updates. This is especially important on Windows and when using terminal multiplexers.
count: agents:2codes: agents:Oes (type-coded with model tier casing)codes-duration: agents:O(2m)es (codes with duration)detailed: agents:[architect(2m),explore,exec]descriptions: O:analyzing code | e:searching (codes + what they're doing)tasks: [analyzing code, searching...] (just descriptions)multiline: Multi-line display with full agent details on separate linesIf the HUD is not showing:
/oh-my-claudecode:hud setup to auto-install and configure/oh-my-claudecode:omc-doctor for full diagnosticsLegacy string format migration: Older OMC versions wrote statusLine as a plain string (e.g., "~/.claude/hud/omc-hud.mjs"). Modern Claude Code (v2.1+) requires an object format. Running the installer or /oh-my-claudecode:hud setup will auto-migrate legacy strings to the correct object format:
{
"statusLine": {
"type": "command",
"command": "node ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hud/omc-hud.mjs"
}
}
Node 24+ compatibility: The HUD wrapper script imports homedir from node:os (not node:path). If you encounter SyntaxError: The requested module 'path' does not provide an export named 'homedir', re-run the installer to regenerate omc-hud.mjs.
Manual verification:
~/.claude/hud/omc-hud.mjs~/.claude/settings.json should have statusLine configured as an object with type and command fieldsThe HUD updates automatically every ~300ms during active sessions.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).