Support external command-based status line with ANSI colors, similar to Claude Code

Support external command-based status line with ANSI colors, similar to Claude Code

Summary

Codex CLI already has a useful built-in status_line picker:

[tui]
status_line = [
  "model-with-reasoning",
  "current-dir",
  "git-branch",
  "context-remaining",
  "five-hour-limit",
  "weekly-limit",
  "fast-mode"
]

It would be very useful to also support an external command-based status line mode, where Codex pipes session/status JSON to a user-configured command and renders the command's stdout in the TUI, preserving ANSI colors.

This would enable richer status lines similar to Claude Code's statusLine.command integration and tools such as ccstatusline.

Motivation

The current built-in segment picker is helpful, but it is intentionally limited:

• Users cannot customize colors per segment.
• Users cannot render custom progress bars.
• Users cannot build multi-line or compact dashboards.
• Users cannot reuse existing prompt/statusline tools.
• Community tooling cannot extend the status line without changes to Codex itself.

For heavy CLI users, the status line is high-value real estate. A configurable command mode would let users show exactly what matters during a coding session, for example:

• model and reasoning effort
• current directory
• git branch/status
• context remaining/used
• five-hour and weekly limits
• token usage
• session cost when available
• fast mode / run state

Proposed config

One possible shape:

[tui.status_line_command]
command = "codex-statusline"
refresh_interval = 10
timeout_ms = 1000
preserve_ansi = true

Alternatively, this could be a variant of the existing setting:

[tui.status_line]
type = "command"
command = "codex-statusline"
refresh_interval = 10
timeout_ms = 1000
preserve_ansi = true

The existing array-based status_line = [...] should continue to work as the default, simple mode.

Runtime behavior

When enabled, Codex would:

1. Build a status JSON payload from the current TUI/session state.
2. Execute the configured command at a bounded interval.
3. Pipe the JSON payload to the command via stdin.
4. Read stdout.
5. Render stdout in the status line area.
6. Preserve ANSI styles when preserve_ansi = true.
7. Ignore stderr or write it to the Codex log.
8. Fall back gracefully on timeout or command failure.

Example JSON payload

The exact schema can evolve, but a first version could include:

{
  "model": "gpt-5.5",
  "reasoning_effort": "high",
  "cwd": "/repo",
  "git_branch": "main",
  "context": {
    "remaining_percent": 82.4,
    "used_percent": 17.6,
    "used_tokens": 176000,
    "window_tokens": 1000000
  },
  "limits": {
    "five_hour": {
      "used_percent": 16.0,
      "resets_at": 1770000000
    },
    "weekly": {
      "used_percent": 12.0,
      "resets_at": 1770300000
    }
  },
  "run_state": "idle",
  "fast_mode": false,
  "codex_version": "0.126.0-alpha.8"
}

Security and reliability considerations

This should be opt-in and disabled by default.

Suggested safeguards:

• Require explicit config before any external command is executed.
• Use a short default timeout, e.g. 1000ms.
• Do not run through a shell unless the user explicitly configures a shell command.
• Consider supporting argv-style config in addition to a string command.
• Avoid passing secrets in the JSON payload.
• Preserve existing behavior when the command fails.
• Log errors instead of rendering stack traces in the TUI.

Why not only add more built-in segments?

Built-in segments are still useful for common cases. However, a command-based mode scales better for customization and community tools. It lets Codex keep a small core while allowing advanced users to build richer local status lines without requiring upstream changes for every new segment or display style.

Related prior art

Claude Code supports a command-based status line where an external command receives status JSON on stdin and renders stdout into the TUI. This has enabled third-party tools such as ccstatusline to provide colorful, compact, multi-line status dashboards.

Codex already has the most important building block: session state in the TUI. Exposing that state to an external status line command would make the feature much more flexible while preserving the current simple picker as the default.