Codex HUD

Codex HUD tails Codex CLI rollout JSONL files and renders a live terminal dashboard.

---

🧭 Overview

Codex HUD tails Codex CLI rollout logs (~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl) and renders a single-pane dashboard optimized for tmux panes or always-on terminals.

🖥️ What the HUD Shows

• Header: HUD title, uptime seconds, optional model label, inferred MCP server count.
• Context usage: Live progress bar, remaining tokens, cached vs. fresh tokens, primary/secondary rate-limit indicators.
• Session info: Working directory (cwd), approval policy, sandbox type, network access flag.
• Tool list: Active tool invocations with elapsed time plus the latest completed tools with ✓/✗ markers (🧰 for MCP tools).
• Agent status: Number of concurrent tools and the latest activity line (redacted when requested).
• Git changes: git status -s output for the inferred repository, pending indicator, and error reporting.
• Footer shortcuts: Persistent q:quit r:reset transient reminder.

🛠️ Setup

git clone https://github.com/Tomatio13/CodexHud.git
cd CodexHud
npm install

🌐 Run from any directory

During development we typically run npm run dev inside CodexHud, but you can globally link the built CLI once and invoke it from any directory.

1. Build the project so dist/index.js exists

   npm run build

2. Link the CLI globally (registers the codex-hud command)

   npm link

3. Run it wherever you like

   codex-hud --sessions-dir "$HOME/.codex/sessions" --today --follow-latest

• Unlink with npm unlink -g codex-hud when you no longer need the global command.
• After modifying source code, re-run npm run build so the linked binary stays in sync.
• If you prefer a custom command name, run npm link --no-bin-links and add an alias such as alias hud-dev='node /path/to/CodexHud/dist/index.js' to your shell config.

🚀 Usage

• Follow the latest rollout of today (recommended):

  npm run dev -- --sessions-dir "$HOME/.codex/sessions" --today --follow-latest

• Screenshot-friendly title/model overrides:

  npm run dev -- --today --follow-latest --title "Codex HUD" --model-label "gpt-5.2-codex"

• Attach to a specific rollout file:

  npm run dev -- --file "$HOME/.codex/sessions/2026/01/03/rollout-2026-01-03T06-34-19-019b80a2-00cf-77d2-8fd7-ad3dbf7b9d02.jsonl"

🔧 Environment Variables

Place optional defaults in .env to skip repeating CLI flags:

SESSIONS_DIR=$HOME/.codex/sessions
MCP_CONFIG=$HOME/.codex/config.toml
CODEX_HUD_THEME_FILE=/path/to/theme.json

Remember to ignore .env files via .gitignore.

🎨 Theme (JSON)

You can override colors/symbols via a JSON theme file. Start by copying assets/themes/default.json and tweak it. Color values accept named colors (e.g. gray, cyan) and HEX (#RRGGBB or #RGB).

npm run dev -- --today --follow-latest --theme-file ./assets/themes/default.json

Only the keys you provide are applied; missing keys fall back to defaults.

Color keys and examples:

Key	Usage	Name example	HEX example
title	Header title	cyan	#00ffff
meta	Model label	magenta	#ff00ff
accent	Accent (bolt icon)	yellow	#ffff00
text	Base text	white	#ffffff
muted	Muted text	gray	#808080
success	Success mark / uptime dot	green	#00ff00
warning	Running mark / active count	yellow	#ffff00
error	Failure mark	red	#ff0000
barFilled	Context bar (filled)	green	#00ff00
barEmpty	Context bar (empty)	gray	#808080

⌨️ Key Bindings

• q: quit the HUD
• r: reset transient state (activity + recent tools)

📚 Additional Docs

• Observed rollout JSONL schema: docs/log-schema.md

---

Japanese Summary

See README_JP.md for the Japanese version.