Codex Usage Status

English | 简体中文

A native macOS menu bar utility that reads data from the local codex app-server and displays:

• Remaining capacity in the rolling 7-day window
• Time until the next reset
• Available reset credits, shown only when the count is greater than zero

The app is read-only. It does not consume reset credits or directly read or record Codex authentication files.

Requirements

• macOS 13 or later
• Codex CLI installed and signed in with a ChatGPT account

Regular users do not need Xcode. Xcode is only required for development or building the app from source.

The app automatically checks these common Codex CLI locations:

/opt/homebrew/bin/codex
/usr/local/bin/codex

You can also select the codex executable manually from the app popover.

Download and install

1. Download the latest CodexUsageStatus-<version>-macos-universal.zip from the project releases page.
2. Double-click the ZIP file to extract CodexUsageStatus.app.
3. Drag CodexUsageStatus.app into the Applications folder.
4. Open CodexUsageStatus from Applications.
5. Look for the usage display on the right side of the macOS menu bar.

This is a menu bar app. It does not open a normal window or show an icon in the Dock.

A release signed and notarized by Apple can be opened normally. If you received an ad-hoc signed development build, right-click the app in Finder, choose Open, and confirm Open again. Only do this for packages from a source you trust.

First-time setup

1. Check the Codex CLI

Open Terminal and run:

codex --version

If a version number appears, the Codex CLI is installed. If Terminal reports command not found and Node.js with npm is already installed, use the official installation command:

npm install --global @openai/codex

Sign in with your ChatGPT account:

codex login

Complete the browser sign-in flow, then verify the session:

codex login status

Codex Usage Status reuses the Codex CLI session. You do not need to enter an API key in the app.

The current version supports Codex signed in with a ChatGPT account. API key and Amazon Bedrock authentication cannot provide the account usage shown by this app.

2. Read the menu bar display

The menu bar uses a compact metric layout:

 76%  │  1d 2h  │   2
 LEFT │  RESET  │ CARDS

• LEFT is the remaining percentage in the rolling 7-day window.
• RESET is the time until the next reset. It updates locally once per minute.
• CARDS is the number of available reset credits. The entire column is hidden when the count is zero or unavailable.
• … means the app is loading data.
• -- means data is currently unavailable. Click the menu bar area to see the error.

3. View details

Click the usage display in the menu bar to open the details popover. It includes:

• Remaining weekly capacity and a progress bar
• Relative and exact reset times
• Available reset credits
• Last update and estimated next refresh times

Use the refresh button in the upper-right corner to fetch fresh data immediately.

4. Configure automatic refresh

Choose one of the available intervals in the Automatic refresh section:

• 10 minutes, the default
• 30 minutes
• 1 hour

The selection is saved automatically. The app also reconciles usage after the Mac wakes from sleep and when a quota reset is reached.

5. Launch at login

After moving the app into Applications, enable Launch at login in the details popover. If macOS asks for approval, open:

System Settings → General → Login Items & Extensions

6. Quit the app

Click the usage display in the menu bar, then click Quit at the bottom of the popover.

Troubleshooting

“Codex CLI not found”

Run codex --version in Terminal first. If Terminal can find it but the app cannot:

1. Open the app popover.
2. Find Codex CLI.
3. Click Choose….
4. Select the actual codex executable.

Common locations:

/opt/homebrew/bin/codex
/usr/local/bin/codex

“Sign in with a ChatGPT account first”

Run:

codex login

After signing in, return to the app and click the refresh button.

Nothing appears in the menu bar

• Open Activity Monitor and search for CodexUsageStatus to confirm that it is running.
• If the menu bar is full, quit some other menu bar utilities.
• Remember that this app does not appear in the Dock.

Usage does not change

• Click the refresh button in the details popover.
• Check that the Codex CLI is still signed in.
• Check whether automatic refresh is set to 1 hour.
• When existing data becomes stale, the app retries with bounded delays of 1, 2, 5, 10, and 30 seconds.

Launch at login does not work

Confirm that the app is in the Applications folder, then turn Launch at login off and on again. If it still fails, check System Settings → General → Login Items & Extensions for a pending approval.

Build and test

Development requires Xcode 26 because the project uses Swift 6. Regular users do not need to run these commands.

xcodebuild \
  -project CodexUsageStatus.xcodeproj \
  -scheme CodexUsageStatus \
  -destination 'platform=macOS' \
  -derivedDataPath /tmp/codex-usage-status-derived \
  CODE_SIGNING_ALLOWED=NO \
  build

xcodebuild \
  -project CodexUsageStatus.xcodeproj \
  -scheme CodexUsageStatus \
  -destination 'platform=macOS' \
  -derivedDataPath /tmp/codex-usage-status-derived \
  CODE_SIGNING_ALLOWED=NO \
  test

To run the optional integration test against the locally installed Codex CLI:

xcodebuild \
  -project CodexUsageStatus.xcodeproj \
  -scheme CodexUsageStatus \
  -destination 'platform=macOS' \
  -derivedDataPath /tmp/codex-usage-status-derived \
  CODE_SIGNING_ALLOWED=NO \
  'SWIFT_ACTIVE_COMPILATION_CONDITIONS=$(inherited) CODEX_INTEGRATION_TESTS' \
  -only-testing:CodexUsageStatusTests/ProtocolDecodingTests/testLiveCodexAppServerWhenEnabled \
  test

To use Launch at login in a local build, build with Sign to Run Locally, move the app into /Applications, and then enable the setting.

Create a release package

Run:

./scripts/package-release.sh

The script creates a Release build and writes these files to dist/:

CodexUsageStatus.app
CodexUsageStatus-0.1.0-macos-universal.zip
CodexUsageStatus-0.1.0-macos-universal.zip.sha256

The ZIP supports both Apple silicon and Intel Macs. Without a distribution certificate, the script uses an ad-hoc signature. This is suitable for local testing or trusted distribution, but macOS will show a security warning on first launch.

For public distribution, sign with a Developer ID Application certificate and submit the app to Apple for notarization:

DEVELOPER_ID_APPLICATION="Developer ID Application: Your Name (TEAMID)" \
NOTARYTOOL_PROFILE="codex-usage-status-notary" \
./scripts/package-release.sh

NOTARYTOOL_PROFILE is the profile name previously stored in Keychain with xcrun notarytool store-credentials. After signing and notarization, upload the ZIP and .sha256 file to the project releases page. Users can then install the app without Xcode.

Refresh behavior

• Available intervals are 10 minutes, 30 minutes, and 1 hour; the default is 10 minutes.
• The menu bar reset countdown updates locally once per minute without making a network request.
• A manual refresh recalculates the next scheduled refresh.
• The app reconciles usage when the quota resets or after waking from sleep with stale data.
• account/rateLimits/updated notifications merge usage fields locally and do not bypass the selected polling interval.