codex-usage

Know how fast you're burning your weekly Codex quota — and whether it'll last until reset.

Codex hid the old rolling 5‑hour limits, leaving one opaque weekly quota that's easy to blow through mid‑week. codex-usage reads your live rate‑limit data and tells you at a glance: are you on pace, and will the quota survive until reset?

Install

curl -fsSL https://raw.githubusercontent.com/mbogdan0/codex-usage/main/install.sh | bash

Installs the codex-usage command to ~/.local/bin and adds the shell alias for you. Open a new terminal and run codex-usage. Requires codex, jq, and python3 on your PATH.

Other ways to install

From a clone:

git clone https://github.com/mbogdan0/codex-usage.git
cd codex-usage && ./install.sh

Manual (no installer):

chmod +x codex-usage.sh
echo 'alias codex-usage="'"$PWD"'/codex-usage.sh"' >> ~/.zshrc
source ~/.zshrc

Uninstall: delete ~/.local/bin/codex-usage and the codex-usage alias line from your shell rc.

Optional: install GNU coreutils (brew install coreutils) for a request‑timeout watchdog.

Usage

codex-usage [options]

Option	Description	Default
-s, --start TIME	Workday start time (HH:MM)	11:00
-e, --end TIME	Workday end time (HH:MM)	18:00
-w, --weekends	Include weekends in the work model	off
-h, --help	Show help and exit	—

codex-usage                          # default weekday 11:00–18:00 model
codex-usage --start 09:00 --end 17:00
codex-usage --weekends

What you get

• Verdict — on plan, burning faster, or spending slower, with the exact percentage.
• Usage bar with a ▲ plan marker for where you should be right now.
• "Will it last until reset?" forecast, with the projected run‑out time.
• Coverage calendar and quota left + reset timestamp.

How it works

Quota is spent while you work, so the tool models a working window (default: weekdays 11:00–18:00), computes where an ideal linear plan would put you right now, compares it to your real usage to derive your pace, and projects depletion from your average pace. Future weekends are excluded unless you pass -w; past weekends still count so history doesn't skew the math.

Reading the calendar: ■ green = day fully covered · ◧ yellow = partly covered · □ red = quota runs out first · · gray = non‑working day · ■ dim = already passed.