codex-usage-bar

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.