A native macOS app with a WidgetKit desktop widget that shows the remaining Codex limits without opening an interactive Codex CLI session.

The widget uses codex app-server and the account/rateLimits/read method, so it reads the same source of data that backs /status in the Codex CLI.

CodexLimitsWidget is an independent project and is not affiliated with, endorsed by, or sponsored by OpenAI.

• Sources/CodexLimitsHost.swift - a small host app that syncs an auth snapshot.
• Sources/CodexLimitsWidget.swift - the WidgetKit extension that reads and renders limits.
• Resources - Info.plist, entitlements, and the app/widget icon.
• codex-limits - a CLI script for printing limits without the interactive TUI.
• build-widget.sh - builds the .app bundle.
• install-widget.sh - builds, installs into /Applications, and registers the widget.

• macOS with WidgetKit desktop widget support.
• Apple Silicon target (arm64-apple-macosx14.0 in build-widget.sh).
• Installed swiftc / Xcode Command Line Tools.
• Installed and authenticated Codex CLI.

./build-widget.sh

The app bundle is created at:

build/Codex Limits.app

./install-widget.sh

The script:

• rebuilds the app;
• installs it to /Applications/Codex Limits.app;
• removes the old /Applications/CodexLimits.app bundle if it is still present;
• opens the host app.

On launch, the host app registers itself through Launch Services, installs or updates the com.pugalol.codexlimits.refresh LaunchAgent, refreshes the rate limit snapshot, and reloads WidgetKit timelines.

After installation, open the macOS widget gallery and search for Codex Limits. The app provides one square widget, Codex Limits, which shows remaining limits and relative reset times.²

When installing from a release DMG, drag Codex Limits.app into Applications, then open the app once. The first launch performs the widget registration and background refresh setup.

GitHub Actions is split into three workflows:

• CI builds the app on pull requests, verifies the app and widget extension are arm64 macOS 14+ binaries, and uploads a DMG artifact.
• Make Release is manually dispatched with a version bump. The default bump is minor, so a release from 0.2.2 becomes 0.3.0. It updates app and widget bundle versions and creates a release/vX.Y.Z pull request.
• Tag Release runs when a release/vX.Y.Z pull request is closed. If the PR was merged, it creates and pushes tag vX.Y.Z, verifies the arm64 macOS 14+ build, creates a DMG, publishes the GitHub Release, and deletes the release branch if GitHub did not delete it with the PR.

To create a release PR, run the Make Release workflow manually. The bump input is prefilled with minor; use that default for the next minor release.

After merging the release PR, the Tag Release workflow creates the tag, builds Codex-Limits-0.2.3.dmg, and attaches it to the GitHub Release.

The host app reads rate limits through codex app-server and writes a short rate-limit snapshot into the widget extension's Application Support directory on launch and when the Refresh Widget button is pressed. The WidgetKit extension reads that snapshot when rendering.

The snapshot stores the account/rateLimits/read response and the update timestamp. It does not copy Codex auth tokens.

The host app registers a user LaunchAgent at launch:

~/Library/LaunchAgents/com.pugalol.codexlimits.refresh.plist

The agent runs /Applications/Codex Limits.app/Contents/MacOS/CodexLimits --refresh every 5 minutes and at load. The refresh command reads limits through codex app-server, writes the snapshot, reloads WidgetKit timelines, and exits.

The widget also asks WidgetKit to refresh its timeline every 5 minutes. macOS may delay or throttle widget updates, so the LaunchAgent is the primary background refresh mechanism. Opening the host app and pressing Refresh Widget forces an earlier refresh.

Print limits in the terminal:

./codex-limits

Print the raw JSON response:

./codex-limits --json

Show all buckets if the Codex CLI returns more than one:

./codex-limits --all

If the widget appears but does not show limits:

1. Open /Applications/Codex Limits.app.
2. Press Refresh Widget.
3. Make sure the codex CLI is authenticated and available from PATH.
4. Rebuild and reinstall:

./install-widget.sh

The source code is licensed under the MIT License. See LICENSE. This license does not apply to Resources/CodexLimits.icns, which is a third-party brand asset and is not sublicensed under MIT.