How do I install the Hud skill?

Run npx skillmds@latest add richard0901/hud in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Hud skill do?

[OMX] Show or configure the OMX HUD (two-layer statusline) It is listed under Coding & Dev Tools on SkillMD.

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Hud?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

richard0901 (@richard0901) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Hud by richard0901 — Agent Skill

Name: Hud
Author: richard0901

File contents

HUD Skill

The OMX HUD uses a two-layer architecture:

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.
Layer 2 - omx hud CLI command: Shows OMX-specific orchestration state (ralph, ultrawork, autopilot, team, pipeline, ecomode, turns). Reads .omx/state/ files.

Quick Commands

Command	Description
`omx hud`	Show current HUD (modes, turns, activity)
`omx hud --watch`	Live-updating display (polls every 1s)
`omx hud --json`	Raw state output for scripting
`omx hud --preset=minimal`	Minimal display
`omx hud --preset=focused`	Default display
`omx hud --preset=full`	All 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:

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

If omx hud shows "No active modes":

This is expected when no workflows are running
Start a workflow (ralph, autopilot, etc.) and check again

---name: huddescription: [OMX] Show or configure the OMX HUD (two-layer statusline)---# HUD SkillThe 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| Command | Description ||---------|-------------|| `omx hud` | Show current HUD (modes, turns, activity) || `omx hud --watch` | Live-updating display (polls every 1s) || `omx hud --json` | Raw state output for scripting || `omx hud --preset=minimal` | Minimal display || `omx hud --preset=focused` | Default display || `omx hud --preset=full` | All 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 StatusLineConfigured in `~/.codex/config.toml`:```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 HUDThe `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## ConfigurationHUD config stored at `.omx/hud-config.json`:```json{ "preset": "focused"}```## Color Coding- **Green**: Normal/healthy- **Yellow**: Warning (ralph >70% of max)- **Red**: Critical (ralph >90% of max)## TroubleshootingIf the TUI statusline is not showing:1. Ensure Codex CLI v0.101.0+ is installed2. Run `omx setup` to configure `[tui]` section3. Restart Codex CLIIf `omx hud` shows "No active modes":- This is expected when no workflows are running- Start a workflow (ralph, autopilot, etc.) and check again

Frequently asked questions

Hud