Codex HUD

Codex HUD is a sidecar terminal HUD for Codex CLI.

It reads local Codex session JSONL files from ~/.codex/sessions, derives live activity state, and renders a compact multi-line status display outside of the built-in Codex footer.

It can now show:

• current context usage against the model context window
• cumulative and last-turn token usage
• available rate-limit percentages when Codex emits them

Preview

GitHub cannot render terminal colors, but the structure and metrics look like this.

Panel

╭────────────────────────────────────────────────────────────────────────────╮
│ ◠ LIVE  ◉ package                                                          │
│ MODEL gpt-5.4                       PROVIDER codelink                      │
│ AGE 25h 49m                         SESSION 019d497c                       │
│ GIT no-git                          SYNC now                               │
│ CLI 0.117.0                                                                │
├────────────────────────────────────────────────────────────────────────────┤
│ 📦 CTX [█████░░░░░] 48%  123.8k / 258.4k                                   │
│ 🧠 TOK  ·  last 123.8k  ·  session 45.0M  ·  out 213.0k                    │
├────────────────────────────────────────────────────────────────────────────┤
│ ▌ ACTIVITY 2 running  ·  50 done  ·  1 kinds                               │
│ › RUNNING exec_command: npm run build  (<1s)                               │
│           exec_command: node dist/cli.js --once --layout panel --ta...     │
│ ✓ DONE   50 total  ·  exec_command×50                                      │
│ x FAILED 3                                                                 │
│ … RECENT  user  ·  example prompt preview text...                          │
╰────────────────────────────────────────────────────────────────────────────╯

Compact

◠ HUD · ◉ package · gpt-5.4 · codelink · 25h 49m
Session 019d497c · Sync now · CLI 0.117.0
📦 CTX [█████░░░░░] 48% 123.8k / 258.4k
🧠 TOK · last 123.8k · session 45.0M · out 213.0k
State 2 running · 50 done · 1 kinds
Run exec_command: npm run build (<1s) · exec_command: node dist/cli.js --on...
✅ DONE 50 total · exec_command×50
x Failed 3
Recent user · example prompt preview text...

Metrics

• CTX: current context usage against the active model context window
• TOK: token usage summary, including latest turn and session total
• ACTIVITY: current running tools, completed tools, and tool kinds seen
• RUNNING: currently active tool calls
• DONE: aggregated completed tool calls
• FAILED: failed tool call count
• RECENT: latest useful user or assistant message preview

Installation

Published npm package

codex-hud is already published on npm. At the moment, the npm latest tag is 0.0.3, so check the published version if you want the registry build instead of the current repo checkout:

npm view codex-hud version

Install the published package:

npm install -g codex-hud
cd /path/to/project
codex-hud init --target-cwd "$PWD"

Recommended for latest repo fixes

If you want the newest local changes from this repository before they are published to npm, install from the repo itself:

cd /path/to/codex-hud
npm install
npm run build
npm install -g .
cd /path/to/your/project
codex-hud init --target-cwd "$PWD"

Then start it with:

codex-hud --layout panel --target-cwd /path/to/project

Local tarball install

Or package the repo first and install the generated tarball:

cd /path/to/codex-hud
npm install
npm run build
npm pack
npm install -g ./codex-hud-0.0.4.tgz

After install, the main command is:

codex-hud --help

After npm publish

Once 0.0.4 or newer is published to npm, installation on a fresh machine becomes:

npm install -g codex-hud
cd /path/to/project
codex-hud init --target-cwd "$PWD"

First-time setup

If you want the manual path instead of codex-hud init, use the steps below.

Register the plugin locally:

codex-hud install-local-plugin

Install hooks for one project:

codex-hud setup --target-cwd /path/to/project --install-hooks

Add --force only when you want to replace an existing codex-hud plugin link or hook block.

Check the environment:

codex-hud doctor --target-cwd /path/to/project

If doctor warns that codex_hooks is disabled, add this to ~/.codex/config.toml:

[features]
codex_hooks = true

Layouts

• panel: framed multi-line HUD
• compact: dense multi-line HUD
• minimal: two-line HUD
• status: single-line status output for shell/tmux integration

CLI usage

codex-hud --layout panel --target-cwd /path/to/project
codex-hud init --target-cwd /path/to/project
codex-hud --layout compact --dock bottom --target-cwd /path/to/project
codex-hud status --target-cwd /path/to/project
codex-hud setup --target-cwd /path/to/project --print-run --print-tmux --print-hooks
codex-hud doctor --target-cwd /path/to/project
codex-hud workbench /path/to/project

Workbench

If you want the closest thing to an in-window Codex HUD today, use the tmux workbench launcher:

codex-hud workbench /path/to/project

Behavior:

• Outside tmux: creates a fresh tmux session for that launch, with Codex on top and HUD on the bottom.
• Inside tmux: splits the current window with a bottom HUD pane, then starts Codex in the current pane.
• The workbench tries to bind each HUD to the specific session JSONL opened by that Codex pane.

Prerequisite:

• tmux must be installed, for example: brew install tmux

Session targeting

When you have multiple Codex sessions, you can pin the HUD to one target:

• codex-hud --target-cwd /path/to/project
• codex-hud --session-id <session-id>
• codex-hud --session-file /absolute/path/to/session.jsonl

tmux helpers

• codex-hud status: single-line output for status-right
• codex-hud workbench: Codex + HUD tmux workbench
• codex-hud setup: print or install hooks/tmux integration for the current project

Local install

To register this repo as a home-local Codex plugin:

codex-hud install-local-plugin

This creates:

• ~/plugins/codex-hud -> symlink to this repo
• ~/.agents/plugins/marketplace.json entry for codex-hud

Plugin manifest

This project now includes a local Codex plugin manifest:

• .codex-plugin/plugin.json
• hooks.json

The manifest is intended for local plugin packaging and discovery. Project-specific hooks should still be generated with codex-hud setup so the current cwd is bound correctly.

Status

Working CLI distribution candidate.

• Session JSONL parsing, watcher refresh, terminal layouts, tmux workbench, local plugin install, hooks setup, and doctor checks are implemented.
• Codex HUD remains a sidecar HUD, not a native Codex footer replacement.