Adapted from the codexnotif repository docs. Private repo.
A Windows/Linux background utility that reads the authenticated Codex CLI's account rate limits and sends deduplicated Discord channel-webhook alerts. Uses only the Python standard library on Linux, never starts a conversation or model request, and never reads or copies Codex credentials.
Monitors weekly quota windows only. One alert per reset cycle at 20% remaining, 10% remaining, and 0% remaining, plus a notification when the weekly quota resets. Default polling interval: 5 minutes.
Task Scheduler or systemd (least privilege, one instance)
-> Python monitor loop
-> Codex app-server over local stdio JSONL
-> normalize rateLimits, retain weekly windows
-> compare with private persistent state
-> Discord HTTPS webhook only when an event is due
The app-server is never exposed over TCP. Timeouts/crashes get bounded exponential retries and forced child cleanup. A Windows byte-range lock or POSIX flock prevents overlapping instances. Weekly windows recognized by duration (6–8 day tolerant range); short-term windows ignored.
Windows (PowerShell):
.\install.ps1 # creates "Codex Usage Notifier" scheduled task
.\set-discord-webhook.ps1 -Test # configure Discord channel webhook
Ubuntu 24.04: see docs/ubuntu-24.04.md for the isolated Python install and systemd user service. Linux console commands: codex-usage-notifier validate|test-notification|print-usage|notify-current-usage|monitor.
config.json — key settings: alert_thresholds_remaining_percent (default [20,10,0]), poll_interval_minutes (5), notify_on_reset, error_notification_cooldown_minutes (360), included/excluded_limit_ids, local_timezone (America/Chicago), discord_critical_mention (off by default).
Private local files (git-excluded): config.json, secrets.json (webhook), installation.json, state.json (dedup), rotating logs.
.\print-usage.ps1 # live usage, no alerts, no state change
.\notify-current-usage.ps1 # post current usage to Discord now
.\check-now.ps1 # run a full check immediately
.\status.ps1 # health, redacted webhook, last result
.\show-logs.ps1 # recent redacted log lines
.\repair-task.ps1 -Start # repair/recreate the scheduled task
.\simulate-threshold-crossing.ps1 -UsedPercent 85 # safe fake-threshold test
@everyone/@here never accepted.black-candle-technologies/codexnotif (private)