CodexNotch

CodexNotch is a small, native macOS menu bar app that shows your remaining weekly ChatGPT Codex quota as an icon and percentage.

What it does

• Displays 68% beside a pie icon that fills with the remaining weekly quota.
• Shows the server-reported ChatGPT plan in the expanded menu when it is recognized.
• Shows the server-reported ChatGPT credits remaining when the usage response provides a valid value.
• Visualizes the remaining weekly quota and time until weekly reset with two progress bars.
• Shows the five-hour remaining percentage when that exact window is reported, and marks when usage details were last updated or a refresh failed.
• Shows available rate-limit reset credits and visualizes time remaining until the next expiry when ChatGPT provides exact grant and expiry metadata.
• Refreshes automatically every 60 seconds and supports manual refresh.
• Shows the installed version and checks GitHub for a newer release when requested.
• Opens the installed Codex app from the menu, with an explicit disabled state when it is unavailable.
• Uses no telemetry, analytics, automatic updater, browser view, or third-party package.

CodexNotch does not create a notch overlay, inspect conversation logs, read prompts, or store conversation metadata.

Preview

Light	Dark

Install

Download the latest universal macOS ZIP from GitHub Releases, unzip it, and move CodexNotch.app to Applications.

The automated release is ad-hoc signed because this repository does not currently have an Apple Developer ID certificate. macOS may require Control-clicking the app and choosing Open on first launch.

Authentication and privacy

CodexNotch reads tokens.access_token and tokens.account_id from CODEX_HOME/auth.json. When CODEX_HOME is not set, it uses ~/.codex/auth.json.

The token is used only in memory for this read-only request:

GET https://chatgpt.com/backend-api/wham/usage

The network session is ephemeral, has no response cache or cookie store, and rejects redirects to another host. Tokens, headers, and response bodies are never logged or persisted by CodexNotch.

The endpoint is an internal ChatGPT endpoint and may change without notice. If the endpoint omits or changes its plan identifier, the app shows the plan as unavailable rather than guessing. CodexNotch does not infer an absolute token allowance from quota percentages.

Update checks are manual. They use a separate ephemeral, unauthenticated request to the fixed CodexNotch repository endpoint on api.github.com; the app does not download or install releases automatically.

Build and test

Requirements: macOS 14 or newer, Xcode 15 or newer, and Swift 5.9 or newer.

swift test
./scripts/verify.sh

Create a local universal release archive:

ARCHITECTURES="arm64 x86_64" ARCHIVE_ARCH=universal ./scripts/release.sh

Release process

1. Update CFBundleShortVersionString in Resources/Info.plist.
2. Merge the verified change into main.
3. Create an annotated tag matching the app version, such as v0.2.0.
4. Push the tag.
5. .github/workflows/release.yml builds and verifies a universal app, creates the ZIP and SHA-256 file, and publishes both files to the GitHub Release.

The workflow rejects a tag that does not match the version in Info.plist.

License

MIT License. See LICENSE.