CodexMeter

CodexMeter is a native macOS menu bar app that keeps your Codex account limits visible at a glance.

!macOS 13+ !Swift !Version

[!NOTE]

CodexMeter is an unofficial community project. It is not affiliated with or

endorsed by OpenAI.

Preview

Menu Bar Popover

Usage History

CodexMeter Usage History window showing browsable quota history and token activity

Interactive Token Activity

CodexMeter interactive Token Activity chart with range selection and hover details

Customizable Popover

CodexMeter popover customization window with quota source, visibility, ordering, and live preview controls

Features

Shows a selected Codex quota directly in the macOS menu bar, with automatic

fallback to the quota with the lowest remaining percentage.

Uses two concentric progress rings:

- outer ring: remaining quota; - inner ring: remaining time before reset.

Highlights normal, over-pace, and low-quota states without relying on color

alone.

Displays the standard 5-hour and weekly Codex quota windows by default, with

reset countdowns and detailed progress bars.

Shows available banked Codex rate-limit resets as one compact lifetime

progress bar and expiration time per reset. This view is read-only and cannot redeem a reset.

Compares remaining quota with remaining time to indicate whether consumption

is on pace.

Refreshes quota on launch, every 10 seconds while the menu is open, every

60 seconds in the background, after a Codex rate-limit update, and on manual request. Account checks and Token Activity polling stay at one-minute intervals. Failed automatic refreshes back off up to five minutes; unchanged token responses do not rewrite history.

Detects Codex account changes and switches quota data without requiring an app

restart.

Supports standalone and npm-installed Codex CLI launchers by supplying common

local runtime paths to the App Server child process.

Preserves the last successful result and marks it as stale when refresh fails.
Supports optional low-quota and over-pace notifications.
Supports push notifications to Bark and Gotify servers when 5-hour or weekly quota resets, with custom icon URL support for Bark.
Supports launch at login.
Includes English, Simplified Chinese, and Traditional Chinese.
Lets the app interface follow the system appearance or stay in Light or Dark

mode independently.

Offers ring, horizontal-bar, stacked-bar, percentage-only, and progress-only

menu bar styles.

Lets users independently show, hide, and reorder quota details, reset

opportunities, Quota History, and Token Activity in the popover. Each returned quota window has its own visibility switch, and the menu bar indicator can use a chosen window or the automatic lowest-remaining fallback. The default popover shows Reset Opportunities, Quota History, and Token Activity while keeping the GPT-Reserve weekly quota hidden.

Includes developer options with presets, custom quota/time sliders, live

preview, safe appearance controls, deterministic quota-state presets, JSON configuration export, and a one-click reset to the accepted 1.0 appearance. Developer-only test data can populate 30 days of quota history and simulate an available app update.

Records local quota history as changes plus 15-minute anchors. The full chart

defaults to the current seven-day reset cycle and can also show the rolling last 7 days, 14 days, or month, plus browsable calendar weeks and months. Historical ranges show observed quota consumption across reset cycles and label incomplete totals as lower bounds instead of estimating missing use. Each reset cycle remains a separate smooth curve beginning at 100%, with long unrecorded periods visibly shaded.

Shows a compact view of the current weekly quota cycle plus the last 30 days

of token activity directly in the menu-bar popover. The full history window can switch token activity between 7 days, 30 days, 90 days, one year, and all locally retained data. One-year data is grouped by week and all-time data by month to remain readable. Token values use compact k, M, and B units instead of scientific notation.

Keeps the menu-bar popover compact with divider-separated quota and token

sections rather than nested card backgrounds.

Provides a resizable, full-screen-capable history window with an integrated

transparent title bar. Hovering a token bar smoothly highlights its bucket, keeps the rule and date centered across every range, and reveals its exact day or grouped week/month plus compact token count.

Shows optional daily and summary token activity from account/usage/read

when the current Codex account supports it.

Accumulates returned daily token buckets locally, clears them on an explicit

account change, and supports 7-, 30-, 90-day, one-year, or unlimited local retention, storage-size reporting, CSV export, and history clearing. CSV exports include both the raw Unix timestamp and a readable ISO 8601 local time with its UTC offset.

Uses native Liquid Glass cards and controls on macOS 26, with the same modern

chart layout and a system-material fallback on earlier supported macOS.

Includes an About window and Sparkle-based signed updates. It checks daily,

supports one-click download/install/relaunch, and can optionally download and install future updates automatically.

How It Works

Changed digits in the menu bar percentage briefly turn red when quota decreases, hold red for half a second, then smoothly fade back over two seconds; the percent sign keeps its normal color.

CodexMeter launches the locally installed Codex CLI as:

codex app-server --listen stdio://

It then communicates with App Server using newline-delimited JSON-RPC messages:

Initialize the local App Server connection.
Read account metadata with account/read.
Read ChatGPT rate-limit windows with account/rateLimits/read.
Read optional banked-reset availability from the same rate-limit response.
Optionally read token activity with account/usage/read when supported.
Record successful quota snapshots and token summaries in account-separated

local SQLite partitions. ChatGPT accounts use a salted, one-way local key; account email and authentication data are never stored.

Refresh when account/updated or account/rateLimits/updated is received.
Recover a stale authentication session by restarting only the local App

Server child process once.

Calculate remaining quota, remaining time, consumption pace, and eligible

history estimates locally.

CodexMeter does not scrape ChatGPT pages, read Codex authentication files, or store access tokens. Authentication and token refresh remain owned by Codex.

Codex App Server is currently an experimental interface intended for local development and debugging, so future Codex releases may require compatibility updates. See the official Codex App Server documentation.

Requirements

macOS 13 or later.
Xcode 27 beta or later when building the current project from source.
A locally installed Codex CLI.
A working Codex login.

Install and sign in to Codex CLI if needed:

npm install -g @openai/codex
codex login

CodexMeter currently discovers codex in these locations:

~/.local/bin/codex
/opt/homebrew/bin/codex
/usr/local/bin/codex
~/.npm-global/bin/codex
~/.nvm/versions/node/*/bin/codex

Build and Run

Clone the repository:

git clone [email protected]:raycalrui/CodexMeter.git
cd CodexMeter
open CodexMeter.xcodeproj

In Xcode:

Select the CodexMeter scheme.
Select My Mac as the destination.
Press Run.

CodexMeter is a menu-bar-only app, so it does not appear in the Dock. Look for the quota indicator in the macOS menu bar after launch.

Download and Install

Download CodexMeter-1.7.0.dmg from the GitHub Releases page, open it, and drag CodexMeter into the Applications folder.

The downloadable build uses an ad-hoc signature and is not notarized. On first launch, macOS may block it. Control-click CodexMeter in Applications, choose Open, and confirm once. A Developer ID certificate and Apple notarization are planned for a future distribution build.

Automatic Updates

Starting with version 1.3.0, CodexMeter uses Sparkle to download, verify, replace, and relaunch the app. Every update archive is signed with a separate EdDSA key, so this works with the existing ad-hoc app signature and does not require a paid Apple Developer account. The private EdDSA key remains in the maintainer's login Keychain and is never stored in the repository or bundled in the app.

Version 1.2.1 does not contain Sparkle, so upgrading from 1.2.1 to 1.3.0 still requires downloading the DMG manually. Once 1.3.0 is installed, later signed updates can be installed inside CodexMeter. Because the app is not notarized, macOS may still show Gatekeeper warnings on a new installation or after an update; Sparkle does not replace Apple notarization.

Development

Build from Terminal:

xcodebuild \
  -project CodexMeter.xcodeproj \
  -scheme CodexMeter \
  -configuration Debug \
  -destination 'platform=macOS' \
  CODE_SIGNING_ALLOWED=NO \
  build

Run the core unit tests:

swift test

If Command Line Tools is selected instead of the full Xcode installation, set DEVELOPER_DIR before running either command.

Pure quota, time, pacing, history, migration, and semantic-version logic lives under CodexMeter/Core. Package.swift exposes only that directory to Swift Package Manager so the core logic can be tested independently of the macOS UI.

Publishing a Sparkle update

After building the unsigned Release app, re-sign the embedded Sparkle framework and then the outer app bundle. This order is required because Xcode removes development headers while embedding the framework:

Scripts/sign_ad_hoc_release.sh /path/to/CodexMeter.app

Create the release DMG from that verified app. Then use Sparkle's bundled generate_appcast utility. The helper below reads the private EdDSA key from the login Keychain, signs the archive metadata, and updates the repository's appcast.xml:

Scripts/prepare_sparkle_update.sh \
  v1.7.0 \
  /path/to/CodexMeter-1.7.0.dmg \
  /path/to/Sparkle/bin

For a prerelease, pass beta as the fourth argument. Upload the exact signed DMG to the matching GitHub Release, commit and push the generated appcast.xml, then verify its download URL before announcing the release.

See AGENTS.md for the project architecture, product rules, verification checklist, and planned developer customization options.

Privacy and Security

CodexMeter communicates with a local Codex process over stdio.
It does not copy or persist Codex access tokens.
It does not read Codex authentication files directly.
It does not log account email addresses or raw authentication responses.
App Server errors use locally authored messages instead of displaying raw

server errors or system exception details that could contain private data.

App Server output is read in bounded chunks. A response line over 1 MiB stops

the child connection and marks the last successful quota as stale; a manual or scheduled refresh can reconnect. Diagnostic stderr stays in an 8 KiB in-memory tail and is never displayed verbatim.

In-app updates require Sparkle 2.9.6 or later and retain HTTPS transport and

EdDSA archive verification.

It separates ChatGPT account history with a salted SHA-256 key derived

locally from the account type and normalized email. Neither the email nor this internal key is included in CSV exports.

It does not add its own analytics or tracking.
Usage history is stored only in

~/Library/Application Support/CodexMeter/UsageHistory.sqlite and can be exported or cleared by the user.

App Sandbox is currently disabled because CodexMeter must launch the user's local Codex executable. This should be reviewed deliberately before any future Mac App Store distribution.

Full history backup and restore

The menu-bar Settings entry opens one resizable window with four categories: General, Menu Bar & Popover, History & Backup, and Developer, followed by About. Existing preferences are preserved. About/update information opens in the same settings window; Usage History remains a separate window.

Open Settings → History & Backup → Backup & Restore to export a .codexmeterbackup file. It includes all retained quota and token history across accounts, database metadata, and the local identity salt needed to match accounts on another Mac. It does not contain login credentials, email addresses, or app preferences. Keep this file private. Previously deleted or retention-pruned records cannot be recovered. CSV remains a separate readable export format.

Restore replaces all local history after confirmation. CodexMeter validates the archive version, SHA-256 checksum, database integrity, schema, and row counts, then saves the existing history in ~/Library/Application Support/CodexMeter/Backups. Quit and reopen the app after restoring; history writes pause until then. Your existing retention preference applies after reopening. An interrupted restore is rolled back before account activation at the next launch. Backups larger than 512 MiB are currently unsupported.

Known Limitations

Codex App Server is experimental and may change without notice.
Codex executable discovery uses common stable install locations and installed

NVM Node versions rather than the interactive shell's PATH.

Notification and launch-at-login behavior must be tested with a signed build.
Token activity is optional and may be unavailable for API-key, Bedrock, or

other account types even when quota windows are available.

Banked-reset availability is account-dependent. Older App Server versions or

unsupported accounts may omit it; CodexMeter does not treat omission as a confirmed zero balance.

Codex currently provides no stable identifier for API-key and Bedrock

accounts. CodexMeter therefore cannot restore separate historical profiles when switching back and forth between multiple credentials of those types; their anonymous history partition is reset on an explicit account change.

The downloadable DMG is ad-hoc signed, not notarized, and not prepared for

the Mac App Store, so first launch may require Control-clicking the app and choosing Open.

Contributing

Issues and pull requests are welcome.

Before submitting a change:

swift test
git diff --check

For menu bar or popover changes, also launch exactly one signed app instance and perform a UI smoke test.

License

CodexMeter is available under the MIT License.

Disclaimer

Codex and OpenAI are trademarks of OpenAI. This project is provided as an independent utility and may stop working when upstream experimental interfaces change.

raycalrui/CodexMeter: A native macOS menu bar app for monitoring Codex usage limits.