# Codex HUD Global Wrapper Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Build a global `codex` HUD wrapper that keeps the existing `codex` command unchanged for the user while rendering a dense, always-visible terminal HUD with model, path, git, tool activity, agent activity, todo progress, and best-effort context/usage signals. **Architecture:** Implement a user-level Node.js TUI wrapper that launches the real Codex binary through a PTY, observes available runtime signals, normalizes them into HUD state, and draws a fixed bottom status area in the same terminal. Install it globally by placing a wrapper `codex` ahead of the real binary and preserve a safe bypass and uninstall path. **Tech Stack:** Node.js 20+ · TypeScript · PTY process bridge · terminal UI rendering · user-level install scripts · zsh/macOS target first --- ## File Structure ``` /Users/manpengan/pro/codex-hud/ ├── package.json ├── tsconfig.json ├── README.md ├── bin/ │ ├── codex-hud │ └── codex-hud-install ├── scripts/ │ ├── install-global.sh │ ├── uninstall-global.sh │ └── doctor.sh ├── src/ │ ├── cli.ts # entrypoint for hud launcher │ ├── install.ts # install/uninstall/doctor commands │ ├── config.ts # local config + defaults │ ├── terminal/ │ │ ├── renderer.ts # bottom HUD drawing │ │ ├── layout.ts # dense/compact layout rules │ │ └── tty.ts # resize, raw mode, cleanup │ ├── launcher/ │ │ ├── resolve-codex.ts # find real codex binary │ │ ├── spawn-codex.ts # launch codex in PTY │ │ └── argv.ts # passthrough args, --no-hud handling │ ├── state/ │ │ ├── store.ts # in-memory normalized HUD state │ │ ├── model.ts # model/session metadata │ │ ├── git.ts # cwd + branch + dirty status │ │ ├── timer.ts # session elapsed time │ │ ├── tools.ts # tool activity tracking │ │ ├── agents.ts # agent activity tracking │ │ ├── todos.ts # todo progress extraction │ │ ├── context.ts # context/usage native-or-estimated signals │ │ └── status-labels.ts # "native", "estimated", "n/a" labels │ ├── observers/ │ │ ├── stdout-parser.ts # best-effort parsing from visible output │ │ ├── app-server.ts # optional official signal source if available │ │ ├── session-files.ts # inspect readable local Codex state when present │ │ └── process-tree.ts # codex child process lifecycle observation │ └── types/ │ └── hud.ts # shared event/state types └── docs/ └── superpowers/ └── plans/ └── 2026-03-21-codex-hud-global-wrapper.md ``` ## Product Rules - The user keeps typing `codex`; no new daily command should be required. - The wrapper must support `codex --no-hud` to bypass the HUD immediately. - The wrapper must not destroy terminal state on crash; cleanup and cursor restore are mandatory. - Dense mode is the default. - Any metric that is not guaranteed by Codex must be marked `estimated` or `n/a`; never invent precision. - Install must be reversible in one command. ## Task 1: Scaffold the project and baseline CLI **Files:** - Create: `/Users/manpengan/pro/codex-hud/package.json` - Create: `/Users/manpengan/pro/codex-hud/tsconfig.json` - Create: `/Users/manpengan/pro/codex-hud/README.md` - Create: `/Users/manpengan/pro/codex-hud/src/cli.ts` - Create: `/Users/manpengan/pro/codex-hud/src/launcher/argv.ts` - [ ] **Step 1: Create package manifest with executable bins** Add package metadata, `type`, build scripts, and bins for `codex-hud` and installer commands. - [ ] **Step 2: Create TypeScript config** Set Node-targeted compilation, strict mode, and `dist/` output. - [ ] **Step 3: Create CLI entrypoint** Parse argv, recognize `--no-hud`, and route either to passthrough mode or HUD mode. - [ ] **Step 4: Add placeholder README** Document scope, supported platform, install model, and safety notes. - [ ] **Step 5: Verify compile shape** Run: `npm run build` Expected: TypeScript builds with stub files present. - [ ] **Step 6: Commit** ```bash cd /Users/manpengan/pro/codex-hud git add . git commit -m "feat: scaffold codex hud project" ``` ## Task 2: Resolve and launch the real Codex binary safely **Files:** - Create: `/Users/manpengan/pro/codex-hud/src/launcher/resolve-codex.ts` - Create: `/Users/manpengan/pro/codex-hud/src/launcher/spawn-codex.ts` - Modify: `/Users/manpengan/pro/codex-hud/src/cli.ts` - [ ] **Step 1: Implement real-binary resolution** Resolution order: 1. explicit env override (`CODEX_REAL_BIN`) 2. stored install manifest path 3. fallback PATH search excluding wrapper path - [ ] **Step 2: Define failure behavior** If real Codex is not found, print a direct recovery message and exit non-zero. - [ ] **Step 3: Launch Codex through a PTY** Use a PTY-backed child so Codex keeps its normal interactive behavior. - [ ] **Step 4: Forward signals** Handle `SIGINT`, `SIGTERM`, and child exit propagation correctly. - [ ] **Step 5: Verify passthrough mode** Run: `node dist/cli.js --no-hud --help` Expected: forwards to real `codex --help`. - [ ] **Step 6: Commit** ```bash git add src/launcher src/cli.ts git commit -m "feat: launch real codex via wrapper" ``` ## Task 3: Build terminal lifecycle management and fixed bottom HUD rendering **Files:** - Create: `/Users/manpengan/pro/codex-hud/src/terminal/tty.ts` - Create: `/Users/manpengan/pro/codex-hud/src/terminal/layout.ts` - Create: `/Users/manpengan/pro/codex-hud/src/terminal/renderer.ts` - Create: `/Users/manpengan/pro/codex-hud/src/types/hud.ts` - [ ] **Step 1: Define HUD state shape** Include model, cwd, git, elapsed, context, usage, tools, agents, todo, and display flags. - [ ] **Step 2: Implement dense layout** Four-line default: 1. model | path | git | elapsed 2. context | usage 3. tools 4. agents | todo - [ ] **Step 3: Implement compact fallback** Auto-switch when terminal height is too small. - [ ] **Step 4: Implement draw/erase cycle** Reserve bottom lines, redraw on state change, and restore cursor position cleanly. - [ ] **Step 5: Handle resize and exit cleanup** On resize, recompute visible HUD lines. On exit, clear HUD area and restore terminal modes. - [ ] **Step 6: Verify manual rendering** Run a local stub state loop and confirm no cursor corruption after exit. - [ ] **Step 7: Commit** ```bash git add src/terminal src/types git commit -m "feat: add terminal hud renderer" ``` ## Task 4: Implement stable state store and always-correct signals **Files:** - Create: `/Users/manpengan/pro/codex-hud/src/state/store.ts` - Create: `/Users/manpengan/pro/codex-hud/src/state/model.ts` - Create: `/Users/manpengan/pro/codex-hud/src/state/git.ts` - Create: `/Users/manpengan/pro/codex-hud/src/state/timer.ts` - Create: `/Users/manpengan/pro/codex-hud/src/state/status-labels.ts` - [ ] **Step 1: Add store with subscribe/update semantics** State changes must be incremental and cheap to redraw. - [ ] **Step 2: Implement cwd + path shortening** Show project path with configurable depth, defaulting to a dense but readable path. - [ ] **Step 3: Implement git branch + dirty signal** Detect branch and working tree changes on an interval and on cwd changes. - [ ] **Step 4: Implement elapsed session timer** Start from wrapper launch, refresh at 1-second granularity. - [ ] **Step 5: Implement model source** Derive from argv/config when available; otherwise show `unknown`. - [ ] **Step 6: Verify baseline HUD data** Run wrapper against a real repo and confirm path/git/timer update correctly. - [ ] **Step 7: Commit** ```bash git add src/state git commit -m "feat: add base hud state sources" ``` ## Task 5: Implement activity extraction for tools, agents, and todo progress **Files:** - Create: `/Users/manpengan/pro/codex-hud/src/state/tools.ts` - Create: `/Users/manpengan/pro/codex-hud/src/state/agents.ts` - Create: `/Users/manpengan/pro/codex-hud/src/state/todos.ts` - Create: `/Users/manpengan/pro/codex-hud/src/observers/stdout-parser.ts` - Create: `/Users/manpengan/pro/codex-hud/src/observers/process-tree.ts` - [ ] **Step 1: Define normalized activity events** Event types: - tool-start / tool-end - agent-start / agent-update / agent-end - todo-progress - [ ] **Step 2: Parse visible Codex output conservatively** Only promote to structured activity when patterns are high-confidence. Ignore ambiguous text. - [ ] **Step 3: Track recent tool activity** Show short rolling summary with counts and active item. - [ ] **Step 4: Track agent activity** Show active worker name, duration, and simple state. - [ ] **Step 5: Track todo progress** Extract `n/m` style progress when visible; otherwise keep hidden or unknown. - [ ] **Step 6: Add staleness handling** Expire old activity after configurable time so the HUD does not freeze on ancient work. - [ ] **Step 7: Verify with recorded output samples** Build fixtures from representative Codex sessions and confirm parser output. - [ ] **Step 8: Commit** ```bash git add src/state src/observers git commit -m "feat: track tool agent and todo activity" ``` ## Task 6: Implement context and usage with native-first, estimate-second strategy **Files:** - Create: `/Users/manpengan/pro/codex-hud/src/state/context.ts` - Create: `/Users/manpengan/pro/codex-hud/src/observers/app-server.ts` - Modify: `/Users/manpengan/pro/codex-hud/src/state/status-labels.ts` - [ ] **Step 1: Probe official signal sources** Inspect whether Codex app-server or readable session artifacts expose native context or usage values. - [ ] **Step 2: Define source precedence** 1. native 2. derived 3. estimated 4. n/a - [ ] **Step 3: Implement context bar rendering** Show percentage with source label when known; otherwise `Context n/a`. - [ ] **Step 4: Implement usage display** Prefer native rate-limit or session usage data. If absent, mark as `estimated` or hide value. - [ ] **Step 5: Refuse false precision** Never display fake percentages without provenance. - [ ] **Step 6: Verify degradation** Test three cases: - native values available - only estimated values available - nothing available - [ ] **Step 7: Commit** ```bash git add src/state/context.ts src/observers/app-server.ts src/state/status-labels.ts git commit -m "feat: add native-first context and usage indicators" ``` ## Task 7: Add installer, global wrapper swap, and rollback safety **Files:** - Create: `/Users/manpengan/pro/codex-hud/src/install.ts` - Create: `/Users/manpengan/pro/codex-hud/scripts/install-global.sh` - Create: `/Users/manpengan/pro/codex-hud/scripts/uninstall-global.sh` - Create: `/Users/manpengan/pro/codex-hud/scripts/doctor.sh` - Create: `/Users/manpengan/pro/codex-hud/bin/codex-hud` - Create: `/Users/manpengan/pro/codex-hud/bin/codex-hud-install` - [ ] **Step 1: Define install manifest** Persist: - real Codex path - wrapper path - install timestamp - version - [ ] **Step 2: Implement global install** Place wrapper in a user-controlled bin directory that is before the real Codex in PATH, or create a symlink strategy if safer. - [ ] **Step 3: Implement bypass** `codex --no-hud` must dispatch directly to the real binary. - [ ] **Step 4: Implement uninstall** Remove wrapper and restore original command behavior without manual cleanup. - [ ] **Step 5: Implement doctor** Verify: - real binary reachable - wrapper is first on PATH - config writable - PTY dependency available - [ ] **Step 6: Verify full install/uninstall cycle** Run install, open a fresh shell, check `which codex`, then uninstall and re-check. - [ ] **Step 7: Commit** ```bash git add src/install.ts scripts bin git commit -m "feat: add global install and rollback workflow" ``` ## Task 8: Add configuration, user overrides, and polished dense defaults **Files:** - Create: `/Users/manpengan/pro/codex-hud/src/config.ts` - Modify: `/Users/manpengan/pro/codex-hud/src/terminal/layout.ts` - Modify: `/Users/manpengan/pro/codex-hud/README.md` - [ ] **Step 1: Add config file support** Store user config under `~/.codex-hud/config.json`. - [ ] **Step 2: Expose dense layout toggles** Allow hiding: - git - context - usage - tools - agents - todo - [ ] **Step 3: Add path depth and color settings** Keep defaults opinionated but overridable. - [ ] **Step 4: Add compact fallback rules** Compact mode must still preserve the most important signals first. - [ ] **Step 5: Update README with configuration examples** Show practical examples, not a full config dump. - [ ] **Step 6: Commit** ```bash git add src/config.ts src/terminal/layout.ts README.md git commit -m "feat: add hud configuration and dense defaults" ``` ## Task 9: Add verification fixtures and end-to-end smoke tests **Files:** - Create: `/Users/manpengan/pro/codex-hud/tests/fixtures/` - Create: `/Users/manpengan/pro/codex-hud/tests/stdout-parser.test.ts` - Create: `/Users/manpengan/pro/codex-hud/tests/layout.test.ts` - Create: `/Users/manpengan/pro/codex-hud/tests/install-smoke.sh` - [ ] **Step 1: Add parser fixtures** Capture representative Codex output for: - tool activity - agent activity - todo progress - unknown/noisy output - [ ] **Step 2: Add unit tests for parser normalization** Ensure high-confidence extraction only. - [ ] **Step 3: Add layout snapshot tests** Verify dense and compact string rendering from known state. - [ ] **Step 4: Add install smoke test** Non-destructive script that checks wrapper resolution and `--no-hud`. - [ ] **Step 5: Run full test suite** Run: `npm test` Expected: all tests pass. - [ ] **Step 6: Commit** ```bash git add tests git commit -m "test: add codex hud parser and install smoke coverage" ``` ## Task 10: Final docs, release workflow, and manual verification **Files:** - Modify: `/Users/manpengan/pro/codex-hud/README.md` - Create: `/Users/manpengan/pro/codex-hud/docs/manual-test-checklist.md` - [ ] **Step 1: Document install and uninstall** Include: - first install - upgrade - bypass - uninstall - [ ] **Step 2: Document metric provenance** Explain which HUD fields are native, derived, estimated, or optional. - [ ] **Step 3: Create manual verification checklist** Cover: - launch in repo and non-repo directories - resize terminal - Ctrl-C / exit cleanup - agent-heavy session - todo-heavy session - `--no-hud` - uninstall/reinstall - [ ] **Step 4: Run final verification** Run: ```bash npm run build npm test ./scripts/doctor.sh ``` Expected: build/test/doctor all succeed. - [ ] **Step 5: Commit** ```bash git add README.md docs/manual-test-checklist.md git commit -m "docs: add codex hud install and verification guide" ``` ## Notes for Execution - macOS + zsh is the primary target for the first pass. - Do not switch to destructive binary replacement first; prefer a user-bin wrapper that wins by PATH order. - If Codex exposes better structured signals during implementation, replace any heuristic parser that the official source makes unnecessary. - If a signal cannot be made trustworthy, surface that explicitly instead of smoothing it over.