codex-hud/docs/superpowers/plans/2026-03-21-codex-hud-global-wrapper.md

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

  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

  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

  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

  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

  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

  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

  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

  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

  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:

  npm run build
  npm test
  ./scripts/doctor.sh
  

  Expected: build/test/doctor all succeed.

• Step 5: Commit

  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.