Codex Statusbar

A useful, persistent status line for the Codex CLI, designed for Codex sessions running in Superset or any terminal.

This is the Codex companion to Ash Brener's Claude Code Statusbar. It carries the original project's statusbar concept and presentation into Codex while using Codex's own TUI state and configuration model.

gpt-5.6-sol high · 5h [██████░░░░] 2h03m · weekly [████████░░] 6d04h · Context 42% used · my-project · main

What it shows

The default footer keeps the information that matters during a coding session visible:

• model and live reasoning effort
• remaining 5-hour and weekly usage allowances
• context-window consumption
• working directory
• Git branch and change counts

This port uses Codex's native tui.status_line and live rate-limit state, with a small source patch that changes the two quota items from percentages into compact bars and reset countdowns. There is no transcript parsing, background poller, API key, or jq dependency. Items that do not apply yet—such as account limits before usage data arrives or Git state outside a repository—are omitted automatically.

The countdown is the time until that allowance resets: minutes under an hour, hours and minutes under a day, then days and hours. It is truncated rather than rounded up. If Codex does not supply a reset timestamp, that item safely falls back to its native percentage display.

Requirements

• macOS on Apple silicon
• Codex CLI 0.153.4
• Node.js 18 or newer for the installer
• Rust/Cargo and Git when building from source

Check your installed CLI with:

codex --version

Install

From this checkout:

npm run build:codex
node bin/cli.js install

Restart Codex after installation. The installer:

1. saves the pre-existing footer settings and global Codex launcher in ~/.codex/.codex-statusbar-backup/manifest.json;
2. copies the patched binary to ~/.codex/codex-statusbar/bin/codex;
3. atomically points the existing global codex launcher at that binary, without changing the official npm package;
4. changes only tui.status_line and tui.status_line_use_colors in ~/.codex/config.toml;
5. installs a $statusbar management skill in ~/.codex/skills/statusbar/.

Re-running the installer keeps the original backup, so uninstall still returns to the configuration from before the first install.

Configure

The easiest option is Codex's native visual editor:

/statusline

It lets you toggle items, reorder them, preview the footer, and choose whether it uses your active /theme colors.

You can also use this package:

node bin/cli.js configure

Or set an exact layout non-interactively:

node bin/cli.js configure \
  model-with-reasoning,five-hour-limit,weekly-limit,context-used,current-dir,git-branch,branch-changes

Use --no-colors to disable theme colors. Run node bin/cli.js help for more examples.

Recommended configuration

The installer writes the equivalent of:

[tui]
status_line = ["model-with-reasoning", "five-hour-limit", "weekly-limit", "context-used", "current-dir", "git-branch", "branch-changes"]
status_line_use_colors = true

Codex also provides native items for context remaining, separate model/reasoning fields, token totals, context-window size, task progress, fast mode, permissions, approval mode, thread metadata, Codex version, hostname, and pull requests. /statusline can still toggle and reorder these items; the patched formatting applies specifically to five-hour-limit and weekly-limit.

Reset and uninstall

Reset to this package's recommended layout:

node bin/cli.js reset

Restore the exact status-line values and global Codex launcher that existed before installation:

node bin/cli.js uninstall

Uninstall removes only the installed skill and patched binary, restores the saved launcher, and restores the two status-line keys. Other Codex configuration is preserved, including edits made after installation. If another installer has changed the global launcher in the meantime, uninstall leaves that newer launcher untouched.

How this differs from the Claude Code version

Claude Code runs a custom command and pipes session JSON to it. Codex does not currently expose a custom footer command: its official configuration accepts an ordered list of built-in item identifiers. This project therefore carries a deliberately small, version-pinned patch to the official Codex source. The patch leaves rate-limit collection and all other TUI behavior native; it only renders the 5-hour and weekly items as ten-segment bars plus time-to-reset.

The patch is pinned to Codex 0.153.4. A global npm upgrade may replace the launcher, and a newer Codex release may change the source around the patch. To upgrade, add or refresh the matching patch, rebuild, test, and run the installer again. The official npm installation remains present beneath the launcher throughout.

The build script uses a practical local release profile: optimization level 1, no cross-crate LTO, and no debug info. That avoids multi-hour upstream release links while producing a compact native executable. Override the defaults with CODEX_STATUSBAR_OPT_LEVEL, CODEX_STATUSBAR_CODEGEN_UNITS, or CODEX_STATUSBAR_BUILD_JOBS if needed.

Official Codex configuration

See the Codex configuration reference for user-level ~/.codex/config.toml and tui.status_line.

License

MIT