mcpField
H
hud

hud

github.com/yeachan-heoAgent workflows33.7k127 installsUpdated 1d ago
Repository

About hud

hud is an OMX skill for displaying Codex status and orchestration state. It combines the built-in statusLine with the `omx hud` CLI and offers presets, live updates, and JSON output.

Key features

  1. 01Codex model, branch, and context status
  2. 02OMX workflow and activity status
  3. 03Live display with `--watch`
  4. 04JSON output for scripts
  5. 05Minimal, focused, and full presets

Use cases

  1. 01Monitor active OMX workflows and turns
  2. 02View Codex context and Git branch status
  3. 03Use HUD state in scripts
  4. 04Adjust display detail for a session

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/yeachan-heo/oh-my-codex --skill hud

After installing, type/hudin Claude Code to confirm it loaded.

Details

From the project README

HUD Skill

The OMX HUD uses a two-layer architecture:

  1. Layer 1 - Codex built-in statusLine: Real-time TUI footer showing model, git branch, and context usage. Configured via [tui] status_line in ~/.codex/config.toml. Zero code required.

  2. Layer 2 - omx hud CLI command: Shows OMX-specific orchestration state (ralph, ultrawork, autopilot, team, pipeline, ecomode, turns). Reads .omx/state/ files.

Quick Commands

CommandDescription
omx hudShow current HUD (modes, turns, activity)
omx hud --watchLive-updating display (polls every 1s)
omx hud --jsonRaw state output for scripting
omx hud --preset=minimalMinimal display
omx hud --preset=focusedDefault display
omx hud --preset=fullAll elements

Presets

minimal
[OMX] ralph:3/10 | turns:42
focused (default)
[OMX] ralph:3/10 | ultrawork | team:3 workers | turns:42 | last:5s ago
full
[OMX] ralph:3/10 | ultrawork | autopilot:execution | team:3 workers | pipeline:exec | turns:42 | last:5s ago | total-turns:156

Setup

omx setup automatically configures both layers:

  • Adds [tui] status_line to ~/.codex/config.toml (Layer 1)
  • Writes .omx/hud-config.json with default preset (Layer 2)
  • Default preset is focused; if HUD/statusline changes do not appear, restart Codex CLI once.

Layer 1: Codex Built-in StatusLine

Configured in ~/.codex/config.toml:

[tui]
status_line = ["model-with-reasoning", "git-branch", "context-remaining"]

Available built-in items (Codex CLI v0.101.0+): model-name, model-with-reasoning, current-dir, project-root, git-branch, context-remaining, context-used, five-hour-limit, weekly-limit, codex-version, context-window-size, used-tokens, total-input-tokens, total-output-tokens, session-id

Layer 2: OMX Orchestration HUD

The omx hud command reads these state files:

  • .omx/state/ralph-state.json - Ralph loop iteration
  • .omx/state/ultrawork-state.json - Ultrawork mode
  • .omx/state/autopilot-state.json - Autopilot phase
  • .omx/state/team-state.json - Team workers
  • .omx/state/pipeline-state.json - Pipeline stage
  • .omx/state/ecomode-state.json - Ecomode active
  • .omx/state/hud-state.json - Last activity (from notify hook)
  • .omx/metrics.json - Turn counts

Configuration

HUD config stored at .omx/hud-config.json:

{
  "preset": "focused"
}

Color Coding

  • Green: Normal/healthy
  • Yellow: Warning (ralph >70% of max)
  • Red: Critical (ralph >90% of max)

Troubleshooting

If the TUI statusline is not showing:

  1. Ensure Codex CLI v0.101.0+ is installed
  2. Run omx setup to configure [tui] section
  3. Restart Codex CLI

If omx hud shows "No active modes":

  • This is expected when no workflows are running
  • Start an explicitly requested supported workflow ($autopilot or $ultragoal) and check again

Comments

Markdown supported