codex-balance

Print the remaining Codex 5-hour and weekly usage limits for status bars, shell scripts, and small desktop widgets.

This is for people who want their current Codex balance visible at a glance instead of manually refreshing the Codex analytics page throughout the day.

5h: 94% | week: 95%

Requirements

• Node.js 20 or newer
• Firefox with an active ChatGPT login
• sqlite3, used to read Firefox’s cookie database
• Playwright Firefox browser binaries

Install the JavaScript dependency and browser binary:

npm install
npx playwright install firefox

Configuration

Useful environment variables:

FIREFOX_PROFILE_DIR=/path/to/profile
FIREFOX_PROFILES_INI=/path/to/profiles.ini
FIREFOX_EXECUTABLE=/path/to/playwright/firefox
CODEX_BALANCE_TIMEOUT_MS=8000 ./codex-balance.js

To inspect Firefox profiles and see which ones have ChatGPT/OpenAI cookies:

./codex-balance.js --list-profiles

The profile list checks both the regular Firefox location and the Firefox Snap location when present.

Use the reported profile path with FIREFOX_PROFILE_DIR if the automatically selected profile is not the one signed in to ChatGPT.

FIREFOX_PROFILE_DIR=/path/to/profile ./codex-balance.js

Usage

./codex-balance.js

Each invocation performs a live headless Firefox refresh. Poll every 10 minutes from your status bar or scheduler to keep runtime and network usage low.

Polybar Example

[module/codex-balance]
type = custom/script
exec = /path/to/codex-balance/codex-balance.js
interval = 600

Then add codex-balance to your Polybar module list.

i3status Example

I recommend running the query via cron and store the result in a file that i3status reads:

*/5 * * * * /bin/bash -c 'FIREFOX_PROFILE_DIR="~/.mozilla/firefox/..." path/to/codex-balance.js > ~/.balance.txt'

order += "read_file balance"

read_file balance {
  path = "~/.balance.txt"
}

Security Notes

This script reads ChatGPT/OpenAI cookies from your Firefox profile and injects them into a fresh headless Playwright Firefox context. It does not open or lock your live Firefox profile.