A colorful, zero-dependency telemetry heads-up display for Codex CLI and Oh My Codex. The product name is Codex HUD, not “Codex Hub.” Its repository is codex-hud, its executable is codex-hud, and its optional launcher is codo.
╭─[ CODEX HUD LIVE TELEMETRY ]───────────────────────────────────────────────────────────╮
⌂ user@workstation cwd:~/project git:main+
◆ MODEL <model> reasoning:high codex:<version> sid:<session> cost:n/a
◈ TOKENS cached:<count> new:<count> out:<count> think:<count> total:<count> ctx:<used>/<window>
CTX █████████░░░ 72% ACCOUNT ████░░░░░░░░ 34% <plan>/<window> reset:Sat 07/25 12:52 EDT
🤖🤖 agents:2 ⬡ mcp:3 ⚡ hooks:1 ● MEMORY:ready project:example
▣ SYSTEM mem:███░░░░░ <used>/<total> node:<rss> codex:<rss> load:<averages> disk:<percent>
◉ OMX [OMX] example/main | team:2 workers | turns:42
╰──────────────────────────────────────────────────────────────────────────────────────────╯
- User, hostname, current directory, project and Git branch/dirty state
- Active model, reasoning effort, approval/sandbox policy, Codex version and shortened session identifier
- Cached input, non-cached input, output, reasoning and total token counts
- Context-window use with a color-coded progress bar
- Account plan, usage window, reset time and available credits
- Active-agent robot indicators, configured MCP count and hook-plugin count
- Optional generic memory-provider status through an environment variable
- RAM, Node/Codex RSS, largest process, load, disk use and uptime
- Full OMX mode, team, turn and workflow status when OMX is installed
- ANSI colors with a
NO_COLORfallback - No third-party Python dependencies and no outbound telemetry
codolauncher with automatic tmux/HUD lifecycle and transparent Codex option forwarding
The HUD does not estimate billing. It shows cost:n/a because Codex session telemetry does not currently provide an authoritative monetary cost.
| Requirement | Status |
|---|---|
Linux with /proc |
Required |
| Python 3.10 or newer | Required |
| Codex CLI | Required by the installer and codo |
| tmux | Required by the installer for the codo HUD pane and status bar |
Oh My Codex (omx) |
Optional, enables the OMX line |
macOS and Windows are not currently supported because process and memory collection use Linux /proc.
git clone https://github.com/ojesusmp/codex-hud.git
cd codex-hud
./install.shBefore changing files, the installer verifies Linux /proc, Python 3.10+, the
Codex CLI, and tmux. If anything is missing,
an interactive install announces the exact prerequisites and asks before
installing them. A non-interactive run stops and requires explicit approval
with --install-prerequisites.
./install.sh --check # read-only prerequisite check
./install.sh --install-prerequisites # approve missing prerequisite installsThe installer then:
- Installs
codex-hudinto~/.local/bin. - Installs
codo, the Codex launcher that manages the tmux HUD pane. - Adds a concise, non-repeating Codex status line only when no user-owned status line exists.
- Adds a clearly marked, replaceable block to
~/.tmux.conf. - Reloads tmux when run inside an active tmux client.
Restart Codex once after installation so it reloads [tui].status_line.
Paste this exact request so “HUD” cannot be mistaken for “hub”:
Install Codex HUD (the heads-up display, not a hub) from
https://github.com/ojesusmp/codex-hud. Follow that repository's README,
run ./install.sh --check first, then run ./install.sh. Do not install an
unrelated package or plugin with a similar name.
codex-hud # render one full frame
codex-hud --watch # refresh every two seconds
codex-hud --compact # render one status-bar-friendly line
codex-hud --tmux # upgrade an existing HUD pane or open a new pane
codex-hud --interval 1 # set the watch refresh interval
codex-hud --version # print the installed version
NO_COLOR=1 codex-hud # disable ANSI color
codo # launch Codex with an automatically managed HUD
codo --search # pass any Codex option through unchanged
codo exec "run tests" # Codex subcommands and arguments also pass throughcodo enters a dedicated tmux session when needed, opens the HUD pane, runs Codex, and removes the pane when Codex exits. It does not change the Codex security policy. All arguments belong to Codex and are forwarded in their original order.
If ~/.codex/codo.config.toml exists, codo loads it as the standard Codex codo profile. This is the recommended place for launcher-specific model, reasoning, sandbox, or approval defaults:
# ~/.codex/codo.config.toml
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"Environment controls are documented in Configuration. Explicit --profile, --model, and model_reasoning_effort arguments suppress the matching launcher default.
Reset timestamps include the date, local time, and timezone, for example Sat 07/25 12:52 EDT. Configure an IANA timezone persistently:
mkdir -p ~/.config/codex-hud
printf '%s\n' America/New_York > ~/.config/codex-hud/timezoneCODEX_HUD_TIMEZONE provides an environment-variable override. See Configuration.
The public HUD does not probe a specific memory product or credential path. Set a display-only status value when desired:
export CODEX_HUD_MEMORY_STATUS=readyThe value is displayed but is never interpreted as a command or transmitted.
- Native Codex footer: a non-repeating model, branch, context, token, limit and session summary.
- tmux status bar: a compact model/token/account/system summary.
- HUD pane: colored multi-line telemetry, progress graphics, robots and OMX state.
See Configuration for the full field list and customization options.
Codex HUD is read-only and operates entirely on-device. It parses only token_count events from the newest Codex session log and never sends telemetry. It does not read credential stores or print authentication values. See Privacy and Security.
- Architecture
- Configuration
- Compatibility
- Privacy
- FAQ
- Troubleshooting
- Contributing
- Support
- Security policy
- Changelog
./uninstall.shThe uninstaller removes the executable and the managed tmux block. A native Codex status line is removed only when it still carries the Codex HUD managed marker.