Skip to content

Latest commit

 

History

History
187 lines (122 loc) · 11.8 KB

README.md

File metadata and controls

187 lines (122 loc) · 11.8 KB

CodexNotch

CodexNotch app icon

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.

macOS 14+ Swift 5.9 Latest release MIT License LINUX DO

Download the latest release · Watch the 26-second demo · 简体中文

CodexNotch English product 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 while a task is running, 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? Running and idle have distinct cues. A normal completion shows a green check for about five seconds, then restores the current activity state.

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

Expand reset-credit details, choose Use reset beside an available credit, and confirm to use that credit; CodexNotch never uses credits automatically or purchases credits.

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

Running and idle are the two steady states. A normal completion shows a green check for about five seconds, then restores running or idle; stopping a task does not signal success. Floating-bar state symbols remain distinct with animations disabled, and recent conversations remain available after the cue fades. 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.
  • Quota and center animations move only while a task is running. Idle and completion keep clear static cues; disabling animations in the app keeps every state 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.

Multiple Codex accounts

CodexNotch can keep several Codex logins side by side and switch between them from Settings → Accounts or the on-demand account drawer in the expanded notch card.

  • All accounts share the active ~/.codex projects, threads, and settings; CodexNotch syncs the .codex-global-state.json workspace pool across switches so sidebar project lists stay intact.
  • Saved auth.json copies are stored locally with 0700/0600 permissions and are never uploaded.
  • The expanded notch collapses multi-account controls to a compact anchor bar by default, supports quota-first/recent/all filters and hover-live quota preview at the top bars, highlights signed-out or unavailable accounts, and shows per-account 5h/7d quotas and reset times.
  • Existing accounts are adopted automatically from Codex Account Switcher on first launch; more can be added with Import using an exported auth.json.

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 use ChatGPT's read-only endpoints; only a confirmed Use reset action sends a credit-redemption request to ChatGPT.
  • 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 stays focused on lightweight local monitoring and quick account switching. It does not terminate Codex tasks in the background without confirmation, 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. Adding a brand-new login requires importing an exported auth.json; CodexNotch does not open its own OAuth flow yet.

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.