Weekly quota, exact reset times, and task status stay beside your MacBook notch.
Your browser, IDE, or any other app can be frontmost—your quota remains visible.
Download the latest release · Watch the 26-second demo · 简体中文
Real app capture with English product callouts: weekly quota, exact reset time, every reset-credit expiry, cross-app visibility, and live task status.
Codex quota is easy to lose behind other windows. CodexNotch keeps the answers that matter beside your MacBook notch, wherever you work:
- How much weekly quota is left?
- Exactly when does it reset?
- Is the task still running?
They remain beside the physical notch while you code, browse, write, or work in another app.
One glance at the notch: quota, reset time, and task status—without changing apps.
| What you want to know | What CodexNotch shows |
|---|---|
| How much quota remains? | A persistent weekly-quota ring or wave ball beside the notch, with the number inside the indicator. |
| When will quota reset? | The exact reset timestamp plus a second-by-second countdown in the expanded card. |
| When does each reset credit expire? | Click N reset credits available to reveal every precise expiry time and countdown. |
| What happens when I switch apps? | Nothing disappears. Quota and status stay visible while another app is frontmost. |
| Is the task running? | A blue activity echo while Codex works, then a clear green check when it finishes. |
The weekly-quota indicator stays beside the physical notch even when no task is active. Switch to your browser, IDE, or another app and the remaining percentage stays visible.
Hover over the notch to reveal:
- Weekly quota and a horizontal progress bar
- The exact reset timestamp and live countdown
- The precise expiry time of every available reset credit
- Active tasks and recent conversations
Quota windows are identified from the returned limit_window_seconds; CodexNotch does not hard-code a five-hour assumption.
CodexNotch is a standalone native macOS app. It does not depend on Atoll, CodexIsland, CC Switch, or another host. Your browser, IDE, or any other app can stay in front while quota, reset time, and task status remain visible.
While Codex works, a blue activity echo shows that the task is still running; completion switches to a clear green check. Click a task in the expanded card to open codex://threads/<thread-id> instead of searching for the conversation again.
From GitHub Releases, prefer CodexNotch-...dmg when the release provides one. Otherwise, use the ZIP archive:
- For a DMG, open the disk image; for a ZIP, unzip the archive.
- In the DMG window, drag
CodexNotch.apponto theApplicationsshortcut. (The ZIP requires dragging the app into Applications manually.) - Sign in to ChatGPT, use Codex once, then launch CodexNotch.
Swift, Swift Package Manager, and Xcode are not required.
A ZIP is also provided as an alternative archive. The current public build uses an ad-hoc signature, so a DMG does not remove the first-launch macOS warning. Choose Open Anyway in System Settings → Privacy & Security, or Control-click the app and choose Open.
CodexNotch reads the default ~/.codex directory. If Codex uses another directory, set CODEX_HOME before launching the app.
Hover over the physical notch and use Settings at the lower-right of the expanded card. You can also open Settings from the notch context menu or app menu.
- Switch between the clockwise quota ring and wave ball
- Choose Chinese or English for the app interface (English by default)
- Show 0–5 recent conversations in the expanded card
- Apply changes immediately and save them locally
- Respect Reduce Motion while preserving static status cues
Macs without a notch automatically use a menu-bar fallback.
Visual and interaction details
- Both compact indicators use matching 24pt alignment containers, keeping icons clear of the camera cutout.
- The quota ring starts at 12 o'clock and progresses clockwise. It is green at 20% or above, red below 20%, and gray when data is unavailable.
- The gradient or wave moves only while a task is running. It remains still while idle, completed, or when Reduce Motion is enabled.
- The card expands downward from the compact island. Its transparent canvas is reclaimed after collapse so it does not intercept clicks outside the notch.
- The quota number stays inside the indicator and is never repeated beside it.
- The authentication token is read only from
CODEX_HOME/auth.jsonand remains in process memory. CodexNotch never writes it to a cache or log. - Quota and reset-credit details come from ChatGPT's read-only usage and reset-credit endpoints.
- Task state is parsed only from rollout JSONL files in
CODEX_HOME/sessions. - Recent-conversation labels are joined by thread ID to Codex's short
threads.titlesummary in read-onlyCODEX_HOME/state_5.sqlite; rollout message bodies,first_user_message, andprevieware ignored. - CodexNotch never records Authorization headers, complete usage responses, user-message bodies, or conversation-title caches.
The usage endpoint is an internal ChatGPT endpoint and its fields may change. If it fails, CodexNotch keeps the last successful quota while task monitoring continues.
Build from source
Contributors need macOS 14 or later and Xcode 15 / Swift 5.9 or newer:
swift test
./scripts/build_app.sh
open dist/CodexNotch.appCreate distributable ZIP and DMG archives:
./scripts/release.shThe release script runs tests, builds the release app, validates its code signature, produces ZIP and DMG archives plus SHA-256 files, and mounts the DMG to verify its bundled app. The DMG improves installation flow; it does not replace Developer ID signing or notarization. To skip signing entirely:
SIGN_IDENTITY=none ./scripts/build_app.shCodexNotch is currently a v1 preview. It does not terminate Codex tasks, estimate cost, sync to the cloud, send remote notifications, animate a pet, or support Mac App Store distribution. ChatGPT Classic is not a monitored target.
CodexNotch is released under the MIT License. If it helps you stay focused—and a little less anxious about quota—consider giving the project a Star.