What does the HUD show?

The bottom layer shows basics like the model name, git branch, and remaining context. The top layer shows orchestration details such as loops, worker count, and turn numbers read from local state files.

What presets are available?

There are three presets: minimal, focused, and full.

Where does the setup step write configuration?

The setup step writes configuration into ~/.codex/config.toml.

Can I get the HUD output as JSON?

Yes, the skill offers a JSON output mode in addition to watch mode.

HUD Skill

SkillDev tools

hud is a skill that shows or configures the OMX HUD, a two-layer statusline for your terminal. It displays which coding task your agent is working on, with the bottom layer showing basics like the model name, git branch, and remaining context, and the top layer showing orchestration details such as loops, worker count, and turn numbers read from local state files.

Use HUD Skill in Claude, ChatGPT or Ahel Desktop

Free. Sign in, add HUD Skill and connect your AI. About a minute.

Claude ChatGPT Ahel Desktop

Also: Claude Code · Cursor · Codex

Then ask your AI: use the HUD Skill skill

Details

Instructions available. Your AI can read the instructions. Execution depends on the setup they require.

Account requirements not reviewed. Check the skill instructions before use; ahel provides instructions and does not run this skill.

No other account needed.

Have the hud skill available in your agent setup.

HUD SkillStart free

What your AI can do with it

Display a two-layer statusline while the agent works
Show model name, git branch, and remaining context in the bottom layer
Show loops, worker count, and turn numbers in the top layer
Offer minimal, focused, and full presets
Provide watch and JSON output modes
Write configuration into ~/.codex/config.toml

Getting started

Have the hud skill available in your agent setup.
Run the skill's setup step to write configuration into ~/.codex/config.toml.
Choose one of the three presets: minimal, focused, or full.
Use watch mode or JSON output mode if you need those views.

What this skill tells your AI

The instructions your AI receives, as published by yeachan-heo/oh-my-codex in skills/hud/SKILL.md and read by ahel’s review.

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 an explicitly requested supported workflow ($autopilot or $ultragoal) and check again

Signals

GitHub stars: 33k
Forks: 3k
Last commit: Oct 2026

Questions

What does the HUD show?: The bottom layer shows basics like the model name, git branch, and remaining context. The top layer shows orchestration details such as loops, worker count, and turn numbers read from local state files.
What presets are available?: There are three presets: minimal, focused, and full.
Where does the setup step write configuration?: The setup step writes configuration into ~/.codex/config.toml.
Can I get the HUD output as JSON?: Yes, the skill offers a JSON output mode in addition to watch mode.
Does the HUD read from local state files?: Yes, the top layer reads orchestration details such as loops, worker count, and turn numbers from local state files.

Advanced

Item type: skill
Key: hud-2
Source: github.com/yeachan-heo/oh-my-codex

github.com/yeachan-heo/oh-my-codex

More in Dev tools

teach
Skill · mattpocock
More in Dev tools implement
Skill · mattpocock
More in Dev tools ponytail
Skill · dietrichgebert
More in Dev tools caveman
Skill · juliusbrussee
More in Dev tools shadcn
Skill · shadcn
More in Dev tools council
Skill · affaan-m
More in Dev tools