codex-usage-bar

A persistent usage bar for Codex CLI that shows rate-limit windows, current session context, reset countdowns, last-turn tokens, and plan information from local Codex session logs.

From the creator of claude-usage-bar: the same compact usage-bar idea, rebuilt around Codex CLI's local ~/.codex/sessions/**/*.jsonl data.

Codex does not currently expose Claude Code's documented statusLine command hook, so this project ships as a local command, a Codex skill, and a Windows Terminal bottom-pane wrapper.

Leggi in italiano

---

Preview

Plain text preview (no color)

Normal   | Codex  |  5h: ██░░░░░░ 12%  reset 3h 42m  |  7d: ░░░░░░░░ 2%  reset 6d 1h  |  ctx: █████░░░ 60%  |  last: 155k tok  |  plan: plus
Warning  | Codex  |  5h: ██████░░ 84%  reset 0h 41m  |  7d: ████░░░░ 55%  reset 1d 6h  |  ctx: ██████░░ 74%  |  last: 181k tok  |  plan: plus
Critical | Codex  |  5h: ███████░ 95%  reset 0h 12m  |  7d: ███████░ 92%  reset 3d 2h  |  ctx: ███████░ 88%  |  last: 210k tok  |  plan: plus

---

Fields

Field	Meaning	Color thresholds
5h, 7d, 30d	Codex rate-limit windows exposed by Codex logs; shown according to WINDOWS / --windows	green < 80% · yellow 80-90% · red >= 90%
reset	Countdown from each limit's resets_at timestamp	hours/minutes if < 24h · days and hours if >= 24h
ctx	Approximate context-window usage for the selected/current Codex session from last_token_usage.total_tokens / model_context_window	green < 70% · yellow 70-80% · red > 80%
last	Last recorded turn token count	informational
plan	Plan type reported by Codex rate-limit metadata	informational

Note: This tool reads local Codex session logs only. It does not call OpenAI APIs and does not read auth.json.

By default, WINDOWS=auto shows only the rate-limit windows from the latest Codex usage event. This avoids stale windows from older sessions or previous plan states. Use WINDOWS=5h,7d to force specific labels, or WINDOWS=all to show every non-expired window detected in local logs. Rate-limit windows are account-level/shared, while ctx is session-specific when the Windows wrapper provides session metadata.

---

Requirements

• Codex CLI with local session logs
• Python 3.8+
• Windows Terminal for the optional bottom-pane wrapper on Windows
• No external Python dependencies

---

Installation

Option 1 - Codex skill

Windows PowerShell:

.\install.ps1

macOS/Linux:

bash install.sh

Then start a new Codex session and ask for $codex-usage-bar or for your Codex usage/status bar.

Option 2 - Local command

Windows PowerShell:

.\codex-usage-bar.ps1 --plain
.\codex-usage-bar.ps1 --watch 5
.\codex-usage-bar.ps1 --json

macOS/Linux:

./codex-usage-bar.sh --plain
./codex-usage-bar.sh --watch 5
./codex-usage-bar.sh --json

Direct Python:

python skills/codex-usage-bar/scripts/codex_usage_bar.py --plain

Option 3 - Windows bottom usage pane

Install permanent PowerShell functions and the codex wrapper:

.\install-powershell-profile.ps1

Open a new PowerShell tab, then run Codex normally:

codex

Available commands:

codex       Codex with the bottom usage pane
codexraw    Original Codex CLI without the wrapper
codexusage  One-shot or --watch usage command

The bottom pane follows the same response-driven update model as claude-usage-bar: it does not visibly refresh on a timer. It polls local Codex session logs quietly and redraws only when a new token_count usage event appears, which happens after Codex records a response. Each pane locks onto the Codex session file created for that wrapper instance, so ctx reflects that session instead of whichever Codex window produced the latest global event.

---

Configuration

Edit usage-bar.conf before installing, or ~/.codex/usage-bar.conf after installing:

LANG=it
COLOR=auto
BAR_WIDTH=8
WINDOWS=auto

Supported languages: en, it.

Supported windows: auto/current, all/available, or a comma-separated list such as 5h,7d, 7d, 30d, 300m, 5h.

You can also tune the Windows pane with environment variables:

$env:CODEX_USAGE_BAR_POLL_INTERVAL = "1"
$env:CODEX_USAGE_BAR_LANG = "it"

---

How it works

Codex writes session events to JSONL files under ~/.codex/sessions. codex-usage-bar scans event_msg entries whose payload type is token_count, extracts rate-limit metadata and token usage, then formats a compact terminal line. Without session arguments it uses the latest token event. With --session-file, or with --session-start plus --session-cwd, context usage is scoped to that session while rate limits remain shared/global.

Relevant fields:

{
  "type": "event_msg",
  "payload": {
    "type": "token_count",
    "info": {
      "last_token_usage": {
        "total_tokens": 155000
      },
      "model_context_window": 256000,
      "rate_limits": {
        "plan_type": "plus",
        "primary": {
          "used_percent": 12,
          "resets_at": 1783800000
        },
        "secondary": {
          "used_percent": 2,
          "resets_at": 1784300000
        }
      }
    }
  }
}

---

File structure

codex-usage-bar/
├── README.md                                      this file
├── preview.svg                                    GitHub preview image
├── usage-bar.conf                                 language/color config
├── install.sh                                     Codex skill installer for macOS/Linux
├── install.ps1                                    Codex skill installer for Windows
├── install-powershell-profile.ps1                 Windows wrapper installer
├── codex-usage-bar.sh                             local command for macOS/Linux
├── codex-usage-bar.ps1                            local command for Windows
├── codex-with-usage.ps1                           Windows Terminal pane wrapper
├── bin/
│   ├── codex.cmd                                  PATH shim for wrapped Codex
│   └── codexraw.cmd                               PATH shim for raw Codex
└── skills/codex-usage-bar/
    ├── SKILL.md                                   Codex skill instructions
    └── scripts/codex_usage_bar.py                 parser and renderer

---

Compatibility

Platform	Status	Notes
Windows PowerShell	supported	full command, skill, and bottom-pane wrapper
macOS	supported	command and skill installer
Linux	supported	command and skill installer

Python standard library only. No API keys, no external packages, no network calls.

---

License

MIT

---

codex-usage-bar - Italiano

Una barra di utilizzo persistente per Codex CLI che mostra finestre di rate limit, contesto della sessione, countdown al reset, token dell'ultimo turno e piano, leggendo solo i log locali di Codex.

Dallo stesso autore di claude-usage-bar: la stessa idea di barra compatta, ricostruita sui dati locali di Codex in ~/.codex/sessions/**/*.jsonl.

---

Anteprima

---

Installazione rapida

Windows PowerShell:

.\install.ps1

macOS/Linux:

bash install.sh

Poi avvia una nuova sessione Codex e chiedi $codex-usage-bar oppure la tua barra di utilizzo Codex.

Per installare il wrapper Windows con pannello inferiore:

.\install-powershell-profile.ps1

Apri una nuova tab PowerShell e usa:

codex

---

Note

• Legge solo i JSONL sotto ~/.codex/sessions.
• Di default WINDOWS=auto mostra solo le finestre dell'ultimo evento Codex corrente; usa WINDOWS=5h,7d per forzarle o WINDOWS=all per mostrare tutte quelle non scadute rilevate nei log.
• Nel wrapper Windows il contesto ctx viene agganciato al file sessione della finestra Codex corrente; i limiti 7d/5h restano invece condivisi a livello account.
• Non chiama API OpenAI.
• Non legge auth.json.
• Se Codex aggiungera un hook nativo tipo status line, lo script potra essere collegato direttamente a quell'hook.