Codex Credits Watcher - Help

A tiny always-on-top desktop widget for Windows that monitors Codex quota status in real time and displays it in a compact, taskbar-friendly layout.

Purpose

This app helps you quickly see your current Codex quota health without opening the full CLI view. It refreshes automatically and is designed to stay minimal, unobtrusive, and glanceable.

Widget Screenshot

Current compact UI reference:

Codex Credits Watcher widget screenshot

Component Guide

  • 5h: 5-hour quota window.
  • Wk: Weekly quota window.
  • Battery icons: quota level (fuller battery means more quota left).
  • ⏳ timers: time remaining until each quota window resets.
  • $ status: credits availability indicator.
  • x button: closes the widget.
  • Apoorva Consulting: clickable link to website.
$ ✓ Credit available
$ ✕ Credit not available
$ ? Credit unknown

Terms and License (Non-Commercial)

This project is released for free, non-commercial use. You may use, modify, and redistribute it for non-commercial purposes with attribution.

  • No commercial use is permitted under this license.
  • Redistributions must keep license and attribution notices.
  • The software is provided "as is" without warranty.

Full text (DE translation): LICENSE.de.txt
Full text (EN, binding): LICENSE

Versioning and Release Notes

Current version: 0.1.0-rc.2
Source of truth: VERSION
Full release history: docs/changelog.md

Community Testing and Feedback

Please test this app with your own Codex CLI setup and account. If you see errors, unexpected status values, or UI issues, please report them in GitHub Issues.

Report here: GitHub Issues

Known Limitation: Credit Balance Value

The widget currently shows credit availability status (`$ ✓ / ✕ / ?`) but does not reliably show numeric billing credit values, because this value is not exposed through the current supported Codex client interface.

Tracking issue: openai/codex#10233

Install Safety (Unsigned RC/Beta Builds)

Some RC/beta binaries may be unsigned and can trigger antivirus warnings. Verify file integrity before running.

Official downloads: GitHub Releases

  • Download codex-credits-watcher-onefile.exe and SHA256SUMS.txt.
  • Optional fallback: codex-credits-watcher-onedir.zip.
  • Do not use GitHub auto-generated Source code (zip) or Source code (tar.gz) for installation.
  • Compute local hash in PowerShell: Get-FileHash .\\codex-credits-watcher-onefile.exe -Algorithm SHA256
  • Confirm it matches the value in SHA256SUMS.txt.

Full guidance: SECURITY.md

How We Got This Working (Technical)

The widget uses a local background Codex app-server session and reads status via JSON-RPC, instead of parsing interactive terminal output. This avoids TTY constraints from `/status` in the interactive UI path.

  • Data path: app sends `account/rateLimits/read` to Codex app-server (`stdio` transport) every 5 seconds.
  • UI mapping: `usedPercent` values are converted to \"quota left\" and rendered as battery levels.
  • Reset timing: `resetsAt` timestamps are converted to compact countdown values (for example `1h 35m`, `5d+`).
  • Credit state: `credits` metadata is mapped to availability icon (`$ ✓ / ✕ / ?`).
  • Runtime behavior: Codex child process is started hidden on Windows to avoid terminal popups.

Tech stack: Python 3, Tkinter UI, subprocess + threading, JSON-RPC over stdio to Codex app-server.

Assumptions / prerequisites:

  • Codex CLI is installed and reachable in PATH (`codex.cmd`, `codex.exe`, or `codex`).
  • User is authenticated in Codex locally (login/session already valid on machine).
  • Machine allows local process execution and outbound network access required by Codex.
  • Codex app-server protocol continues to expose rate-limit fields used by this widget.