QuotasWatcher

Inspiration

QuotasWatcher started with a simple problem: Codex usage limits were easy to forget and inconvenient to check while working. I also had a MacBook with a Touch Bar that deserved something more useful to display.

The idea became a small macOS utility that keeps the current Codex quota visible at a glance—without opening another window or interrupting the workflow. Later, I added Bark notifications so important quota events could reach an iPhone even when I was away from the Mac.

What it does

QuotasWatcher is a native macOS menu bar and Touch Bar application that:

• Displays the remaining Codex quota and its reset time.
• Supports five-hour and weekly quota windows.
• Falls back to weekly usage when OpenAI does not return a five-hour window.
• Shows the number of banked full-reset credits.
• Refreshes automatically while preserving the last valid reading during failures.
• Sends configurable Bark notifications for scheduled resets, bonus resets, and increases in the reset bank.
• Supports English and Simplified Chinese.

The remaining quota is calculated from the percentage reported as used:

$$ \text{remaining} = \max(0,\min(100,100-\text{used})) $$

How I built it

I built QuotasWatcher in Swift using AppKit and Swift Package Manager.

Instead of scraping a webpage, the application launches the local Codex app-server and communicates with it through JSON-RPC. It initializes the server, requests account/ rateLimits/read, parses the returned quota windows, and classifies them by duration rather than assuming a fixed response order.

The interface uses native macOS components:

• An NSStatusItem for the menu bar.
• An NSPopover for quota details and controls.
• NSTouchBar views for compatible MacBook Pro models.
• Native .lproj resources for localization.

Quota observations are persisted locally so consecutive readings can be compared. Scheduled resets are identified when the reported reset boundary advances near the expected time. Unexpected quota increases are treated as bonus resets, while reset-bank notifications use changes in the explicit available-reset count.

Bark notifications are sent as JSON requests to the user’s device endpoint. Notification categories can be enabled independently, and the Bark key is stored only in local application preferences.

Challenges

One of the biggest challenges was that the quota response is not completely stable. The five-hour window may be absent, and primary and secondary windows are not always in the same positions. Classifying windows by their reported duration made the application more resilient to these changes.

Reset detection was another challenge. A quota increase can mean a scheduled reset, a bonus reset, or simply stale observations being compared after the application was closed. QuotasWatcher limits ordinary quota comparisons to observations no more than 30 minutes apart. Reset-bank increases are safer to detect across longer gaps because the API provides an explicit count.

Process management also required care. The application must launch the Codex app-server, complete its JSON-RPC handshake, handle partial output, enforce timeouts, and preserve the previous quota display when a refresh fails.

Finally, fitting useful information into the limited space of a menu bar and Touch Bar required a compact design that remains understandable in both supported languages.

What I learned

This project taught me a great deal about building small but dependable native macOS utilities. I gained experience with AppKit lifecycle management, menu bar applications, Touch Bar integration, Swift concurrency, process communication, JSON-RPC, localization, persistent preferences, and testable event-detection logic.

More importantly, I learned that integrations should be designed for changing upstream data. Optional windows, reordered fields, transient network failures, and evolving quota behavior are normal conditions—not exceptional ones. Building around those realities made QuotasWatcher much more robust.

Built With

• appkit
• bark
• codex
• json-rpc
• localization
• macos
• menu-bar-app
• rest-api
• swift
• swift-package-manager
• touch-bar
• xctest