CodexMeter

English | 简体中文

CodexMeter is an unofficial macOS menu bar app for viewing Codex / ChatGPT account quota status and quickly switching between local Codex accounts.

It reads from and writes to your local ~/.codex/auth.json, making it useful for users who frequently switch Codex accounts or want to keep an eye on 5-hour quota, weekly quota, and reset credits.

Features

• Shows Codex quota information in the menu bar, including 5H quota, weekly quota, and reset credits.
• Adds accounts through the ChatGPT OAuth login flow.
• Supports saved account lists, account switching, token refresh, and quota refresh across all accounts.
• Automatically backs up the current auth.json before switching accounts.
• Supports launch at login, menu bar display items, separators, and quota component display settings.
• Provides privacy and storage settings so local data paths are easy to inspect.

Project Status

CodexMeter is a personal tool and is not an official OpenAI application. It depends on the current behavior of ChatGPT / Codex OAuth and quota endpoints, which may change in the future.

Tokens and account information are stored only in local JSON files, but they are sensitive credentials. Do not commit accounts.json, auth.json, or backup files to your Git repository.

Requirements

• macOS
• Xcode 26 or later
• Swift 5

The current Xcode project is configured with a macOS 26.5 deployment target. If you want to support earlier macOS versions, adjust the deployment target in Xcode and verify the app again.

Build and Run

1. Clone the repository:

   git clone https://github.com/<your-name>/CodexMeter.git
   cd CodexMeter

2. Open the Xcode project:

   open CodexMeter.xcodeproj

3. Select the CodexMeter target in Xcode and configure your Signing Team if needed.

4. Run the app. CodexMeter is a menu bar app and does not show a Dock icon after launch. Look for it in the macOS menu bar.

Usage

• Click the menu bar icon to open the status panel and view the current account, quota status, and account switching list.
• Right-click the menu bar icon to open the shortcut menu for adding accounts, refreshing, opening settings, or quitting.
• Open Settings... to configure launch behavior, accounts, local storage, privacy information, and menu bar display.
• Use Add Account to open the ChatGPT login flow in your browser and save the account after login.
• Use Switch to write the selected account to ~/.codex/auth.json. Restart any running Codex clients after switching.

Reset credit timeline

The number is the total available reset-credit count, while the compact timeline plots only the nearest expiration and the Weekly quota reset. Each account uses its own comparison window: it starts now and ends shortly after the later of those two events. The open ring progresses clockwise from its lower-left opening; the bar moves from left to right. The colored segment ends at the nearest expiration, and the diamond sits on the track at the Weekly reset. The credit's full lifetime affects urgency color, not timeline length. Later credits remain available in the Settings detail list. The compact app UI omits the explanatory labels shown above; hover the credit point or Weekly marker for its exact time. The diagram shows the orange attention state as an example.

The nearest credit is red when it expires no later than the Weekly reset and Weekly quota is being consumed faster than the remaining time in that window. It is orange when less than 20% of its own lifetime remains. Otherwise it is green when the Weekly reset context is known, and gray when the required context is unavailable.

Open the annotated HTML explanation (download or open it locally if GitHub shows the file source).

Local Data

CodexMeter uses the following local paths:

• Account list: ~/Library/Application Support/CodexMeter/accounts.json
• Auth backups: ~/Library/Application Support/CodexMeter/Backups/
• Codex runtime auth: ~/.codex/auth.json

The app attempts to store these files with owner-only permissions.

References and Acknowledgements

This project references and adapts ideas or code from the following open source project:

• exelban/stats - Parts of CodexStatsMenuBarKit.swift are copied or adapted from this project to implement menu bar components and settings interactions. The upstream project is licensed under the MIT License, and the relevant copyright and license notice is preserved in the source file.

Thanks to the open source projects that provided useful ideas and implementation foundations.

License

This project is licensed under the MIT License. See LICENSE.

Third-party code snippets remain subject to their original license notices.