codex-limit-monitor-waybar/README.md

Codex Usage Monitor for Waybar

A Waybar custom module that displays your Codex 5-hour and weekly rate-limit usage, plus the 5-hour reset countdown.

Default display:

5H 22% · W 18% · 2h55m

It reads usage through the installed Codex CLI's account/rateLimits/read app-server method. It does not read or transmit raw authentication tokens.

Requirements

• Codex CLI logged in with ChatGPT
• Python 3.11 or newer
• Waybar with custom module support

Install

Install the commands without changing Waybar:

./install.sh

Install and configure the module in a selected Waybar section:

./install.sh --configure-waybar --section right --restart

The configurator backs up config.jsonc and style.css, preserves JSONC comments, avoids duplicate module entries, and aborts if it cannot identify the requested module section safely.

Manual Waybar Setup

Add custom/codex-usage to any one of modules-left, modules-center, or modules-right.

Add this module definition to ~/.config/waybar/config.jsonc:

"custom/codex-usage": {
  "exec": "codex-waybar",
  "return-type": "json",
  "interval": 60,
  "tooltip": true
}

Then restart Waybar:

omarchy restart waybar

Formatting

Formatting is configured in Waybar's exec command, like other custom module command options:

"custom/codex-usage": {
  "exec": "codex-waybar --format '5H {five_hour_used}% | W {weekly_used}% | {five_hour_reset_in}'",
  "return-type": "json",
  "interval": 60
}

Available placeholders:

Placeholder	Meaning
{five_hour_used}	5-hour usage percentage
{weekly_used}	Weekly usage percentage
{five_hour_reset_in}	Time remaining until the 5-hour reset
{weekly_reset_in}	Time remaining until the weekly reset
{five_hour_reset_at}	Local 5-hour reset date and time
{weekly_reset_at}	Local weekly reset date and time
{plan}	ChatGPT plan reported by Codex

Other command options:

--tooltip-format TEMPLATE
--warning PERCENT       default: 70
--critical PERCENT      default: 90
--timeout SECONDS       default: 10
--no-cache

Styling

The command emits these Waybar CSS classes:

• normal
• warning
• critical
• stale: the live refresh failed and cached data is displayed
• unavailable: no live or cached data is available

Example:

#custom-codex-usage {
  margin: 0 7.5px;
}

#custom-codex-usage.warning {
  color: #d8a657;
}

#custom-codex-usage.critical,
#custom-codex-usage.unavailable {
  color: #a55555;
}

#custom-codex-usage.stale {
  opacity: 0.65;
}

Troubleshooting

Run the module directly. It always prints Waybar-compatible JSON:

codex-waybar | jq

If it reports unavailable usage, confirm that codex is installed and logged in:

codex login status

The last valid response is cached at ${XDG_CACHE_HOME:-~/.cache}/codex-waybar/rate-limits.json. The cache contains rate-limit percentages and reset timestamps, not credentials.

Development

Run the tests:

python -m unittest discover -s tests -v

Run directly from the repository:

./bin/codex-waybar | jq

Uninstall

Remove the installed commands:

rm ~/.local/bin/codex-waybar ~/.local/bin/codex-waybar-configure

Remove custom/codex-usage from your Waybar module list and module definition, then remove its CSS rules.