| name | codex-usage-bar |
| description | Show current Codex CLI usage from local session logs, including token context usage, rate-limit windows, reset countdowns, and plan information. Use when the user asks for Codex usage, token usage, context window usage, rate limits, reset time, quota, or a usage/status bar. |
Codex Usage Bar
Quick Start
Run the bundled script without loading or reimplementing it:
python scripts/codex_usage_bar.py --plain
Use --json when the user asks for machine-readable values. Use --watch 5 for a periodically refreshed terminal view. Use --windows 5h,7d, --windows 7d, or --windows all only when the user asks for specific rate-limit windows; otherwise leave the default auto behavior. Use --session-file or --session-start plus --session-cwd when context usage must be scoped to a specific Codex session.
Data Source
Read only Codex session logs under $CODEX_HOME/sessions or ~/.codex/sessions. Do not read auth.json, SQLite databases, or unrelated Codex state.
The script uses the latest event_msg whose payload type is token_count. It reports:
- context usage from
last_token_usage.total_tokens / model_context_window; this is session-scoped when a session file/start/cwd is provided
- rate limits from
rate_limits.primary and rate_limits.secondary; by default only windows from the latest usage event are rendered, while --windows / WINDOWS can force or expand the displayed set
- reset countdowns from each limit's
resets_at
- plan from
rate_limits.plan_type
Caveats
Codex does not currently expose the same documented statusLine command hook used by Claude Code. Treat this as a local usage command/skill. If a future Codex status-line hook exists in the local manual or config help, wire this script to that hook instead of changing the parser.
