CodexNotch

Your Codex quota—always in sight.

Weekly quota, five-hour details, 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.}

New in 0.2.2

• Optional launch at login and an Off choice for the left display area to reduce menu-bar overlap.
• Settings grouped into General, Appearance, and Floating Bar, with clearer descriptions.
• Preview floating-bar styles and task states without an external display.
• The animation switch works independently of system Reduce Motion; disabling animations reduces resource use while quota and task updates continue.
• Fixed redundant Settings activation that could interrupt dropdown menus.

New in 0.2.1

• Bring an already-open Settings window back to the front.
• Download, verify, install, and relaunch updates inside the app. Install 0.2.1 manually once when upgrading from an earlier version.

New in 0.2.0

• Gentle hover feedback, a spring opening with a small landing rebound, and a smoother collapse.
• Cleaner typography and spacing, with text staying at its natural size during transitions.
• Four floating-bar center styles: a custom signature, orbit, elapsed time, and light flow. Signature lighting moves continuously while the compact bar is visible and motion is enabled.
• Better-balanced floating status icons and current Codex task names, filtering attachment headers and decoding escaped characters in conversation labels.

Why CodexNotch exists

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, and what is the five-hour detail?
• 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.

At a glance

What you want to know	What CodexNotch shows
How much quota remains?	On a physical notch, a returned five-hour ring or wave ball sits on the left and weekly stays on the right; the expanded card lists five-hour first, then weekly.
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 experience

Quota at a glance, in every app

The left side shows five-hour quota when available, or the selected status icon otherwise. Weekly quota stays on the right even when no task is active. Choose Off in Settings to hide the left side; the expanded card still shows all available quota windows, with five-hour detail above weekly. Switch to your browser, IDE, or another app and the quota remains visible.

Exact reset timing, not just a percentage

Hover over the notch to reveal:

• The returned five-hour quota first, followed by weekly quota, with horizontal progress bars
• 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. On both notch and floating-bar layouts, weekly quota stays on the right; the left side shows five-hour quota when available unless Off is selected. The expanded card lists five-hour detail first.

Your quota follows you across apps

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.

Task status in the same place

While Codex works, a blue activity echo and restrained halos behind the real visible quota indicators show 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.

Install

From GitHub Releases, prefer CodexNotch-...dmg when the release provides one. Otherwise, use the ZIP archive:

1. For a DMG, open the disk image; for a ZIP, unzip the archive.
2. In the DMG window, drag CodexNotch.app onto the Applications shortcut. (The ZIP requires dragging the app into Applications manually.)
3. 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.

Make it yours

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 a floating-bar center style and set a signature of up to 12 characters
• Choose Chinese or English for the app interface (English by default)
• Show 0–5 recent conversations in the expanded card
• Check for stable updates and download, install, and relaunch inside the app (from 0.2.1)
• Apply changes immediately and save them locally
• Start automatically at login when enabled in General
• Hide the left display area while keeping quota details in the expanded card
• Control animations with the app's own switch, independently of system Reduce Motion

Displays without a notch, including mirrored displays, use a floating bar centered at the top of the screen.

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 quota gradient or wave moves only while a task is running. Signature lighting also continues while idle or completed; disabling animations in the app keeps both still.
• 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.

Data and privacy

• The authentication token is read only from CODEX_HOME/auth.json and 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.
• Conversation labels use the latest short thread_name in CODEX_HOME/session_index.jsonl, falling back to threads.title in read-only CODEX_HOME/state_5.sqlite. Rollout message bodies, first_user_message, and preview are ignored when resolving titles.
• CodexNotch never records Authorization headers, complete usage responses, user-message bodies, or conversation-title caches.
• Manual update checks read a public GitHub appcast and download signed release archives; they send no Codex credentials, quota data, task data, or user content.

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 Xcode 16 or newer and a macOS version supported by that Xcode release. The built app supports macOS 14 or later. CI uses Xcode 16.2 on macOS 14:

swift test
./scripts/build_app.sh
open dist/CodexNotch.app

Create distributable ZIP and DMG archives:

./scripts/release.sh

The release script runs tests, builds the release app, validates its code signature, produces ZIP and DMG archives plus SHA-256 files, mounts the DMG to verify its bundled app, and signs the ZIP to generate an update feed using the publisher’s Keychain. See the publisher update workflow. The DMG improves installation flow; it does not replace Developer ID signing or notarization. To skip signing entirely:

SIGN_IDENTITY=none ./scripts/build_app.sh

Current boundaries

CodexNotch is currently in its 0.x release series. It does not terminate Codex tasks, estimate cost, sync to the cloud, send remote notifications, download or install updates without user action, animate a pet, or support Mac App Store distribution. ChatGPT Classic is not a monitored target.

License

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.