A minimal, unofficial VS Code extension that shows OpenAI Codex CLI rate-limit
usage in the status bar. Reads local rollout files only — no network calls, no
auth.
Features
Shows each rate-limit window Codex reports (5h, daily, weekly, monthly, ...)
with usage percent and time to reset.
Click the status bar item for a quick-pick summary with exact reset times.
Warns (yellow) at 75% used and errors (red) at 90% used.
How it works
Codex CLI writes rollout files to:
~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
The extension scans recent rollouts and uses the latest token_count event
with rate-limit data. It never writes to these files or calls out to the
network.
The rollout JSONL structure and its rate_limits field are undocumented Codex
CLI implementation details, not a stable public API. They may change without
notice and break this extension. See the official Codex CLI documentation
and documentation index.
Settings
Setting
Default
Description
codexStatusBar.codexHome
""
Codex home directory. Empty means ~/.codex.
codexStatusBar.refreshIntervalSeconds
60
How often to re-read the latest rollout file.
codexStatusBar.lookbackDays
7
How many days back to search for rollout files.
Commands
Command
Description
Codex Status Bar: Refresh
Re-scan and update the status bar.
Codex Status Bar: Show Usage
Show the usage summary quick-pick.
Codex Status Bar: Open Sessions Folder
Reveal ~/.codex/sessions in the OS.
Development
npm install
npm run compile
npm test
Press F5 to launch an Extension Development Host.
Limitations
Codex exec mode may emit rate_limits: null; those events are skipped.
Usage only updates as often as Codex writes new rollout data.
Codex CLI rollout formats can change without notice because they are not a
supported integration API.
