Add TUI usage status line items for context and token usage
What variant of Codex are you using?
CLI
What feature would you like to see?
Persistent TUI footer/status line items that show context usage and token usage with progress bars and percentages.
Additional information
Summary
I implemented a local branch that adds Codex TUI status line items for context/token usage.
Compare URL:
https://github.com/openai/codex/compare/main...wruty:codex:add-tui-usage-status-line-items?expand=1
Motivation
It would be useful for Codex CLI users to see context usage and token usage persistently in the TUI footer/status line, similar in spirit to Claude Code status line tools.
This helps users understand how close they are to context or token limits while Codex is open.
Implemented locally
- Added TUI status line items for context/token usage.
- Added progress-bar display for context usage and token usage.
- Added compact usage-bars summary item.
- Documented usage in docs/config.md.
- Updated config schema.
- Fixed Windows-specific TUI test expectation failures.
Added status line items
- context-usage-bar
- context-usage-percent
- context-used-tokens
- context-window-tokens
- token-usage-bar
- token-usage-percent
- token-used
- token-limit
- usage-bars
Behavior
- Context usage uses real context token count and model context window.
- Token usage is displayed only when a reliable internal token limit is available.
- Unknown, invalid, or zero max values are rendered as unknown instead of guessed.
- This does not represent API billing tokens.
Manual local TUI check
Local build verification was required because global Codex v0.128.0 does not include these new status line items.
Confirmed with local build:
- OpenAI Codex v0.0.0 was launched from codex-rs\target\debug\codex.exe.
- No "Ignored invalid status line items" warning appeared.
- The footer/status line rendered:
Ctx [----------] unknown · Tok [----------] unknown · Ctx unknown unknown/unknown | Tok unknown unknown/unknown
Recommended config:
[tui]
status_line = ["usage-bars"]
Progress-bar item check:
[tui]
status_line = ["context-usage-bar", "token-usage-bar", "usage-bars"]
Tests
- git diff --check: passed
- cargo fmt --all: passed; emitted an existing stable warning for imports_granularity = Item
- cargo test -p codex-tui compose_agents_summary -- --nocapture: passed
- cargo test -p codex-tui usage_bar -- --nocapture: passed
- cargo check -p codex-tui --message-format short: passed
- cargo clippy -p codex-tui --all-targets -- -D warnings: passed
- cargo test -p codex-tui: passed; 2100 passed; 0 failed; 5 ignored
Note
I could not open a pull request because the repository currently limits pull request creation to collaborators.
The compare URL above contains the implemented local branch.
5 Comments
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
/statusbarallows you to configure what appears within the status bar. The options you're looking for (context window percentage and token usage) are already supported.Thanks, I confirmed that
/statusbarcan show:This covers the persistent percentage display I wanted.
The remaining difference is visual format: I was specifically trying to show context/token usage as progress bars, e.g.
Ctx [######----] 62%
Tok [####------] 41%
If progress-bar rendering is intentionally out of scope for the built-in status bar, I’m fine closing this issue or narrowing it to a progress-bar display request only.
I recently made a change to show a visual bar for the context window like the one you're suggesting here, and we received a lot of negative feedback about it, so I reverted it. The problem is that a visual gauge is easy to misinterpret (does it mean remaining or used) and it takes up significant real estate. So I'm reluctant to add that back.
For token counts, a gauge doesn't make sense because it's an absolute count, not a percentage.
Thanks for the context. That makes sense.
I confirmed that the built-in
/statusbaralready covers the persistent status display I needed with context percentage, 5h usage, and weekly usage.Given the prior negative feedback around visual bars and the ambiguity between used vs remaining, I’m fine closing this issue.
For my use case, I’ll rely on the existing
/statusbaroutput instead.