Codex Quota — macOS Quota Monitor

A privacy-conscious, open-source Swift utility for monitoring Codex quota on Apple Silicon Macs.

macOS 14+ · Apple Silicon · Swift 6.2 · MIT · Source-only v0.1.0

Codex Quota is a small macOS utility that sits at the edge of the screen and shows remaining Codex quota in a square floating panel. It does not occupy the menu bar or remain in the Dock.

Build from source · v0.1.0 source release · Review privacy and security · Good first issues · Contribute

At a Glance

• Live quota for the confirmed current account.
• A last-confirmed snapshot for a second bound account.
• A compact floating edge panel instead of a menu bar or Dock item.
• Optional local notifications, disabled by default.
• No project-operated telemetry, cloud sync, or remote service.
• Reduce Motion, Reduce Transparency, and Increase Contrast support.

If Codex Quota is useful, star the repository or help with a bounded, privacy-safe newcomer task.

Project Status and Unofficial Notice

Codex Quota is an independent community project. It is not affiliated with, endorsed by, or sponsored by OpenAI. Codex and OpenAI are trademarks of OpenAI.

This repository currently provides source code only. There is no signed or notarized download for end users. The app does not sign in to Codex on your behalf and does not modify Codex account or authentication files.

Synthetic Interface Preview

The following diagram uses fictional accounts and quota values. It is not a screenshot from a real user:

Compact                       Expanded
┌────────────────┐          ┌────────────────────────┐
│  δ  82%         │          │  δ  82%  Live          │
└────────────────┘          │  ε  61%  Last confirmed│
                            └────────────────────────┘

The compact panel shows only the current account. The expanded panel shows both bound accounts. Account 1 defaults to a blue δ, and Account 2 defaults to a red ε. Marker color distinguishes accounts; percentage color represents only remaining quota. A percentage always uses one solid color.

All interface previews and test data in this project must be synthetic. Do not submit screenshots containing real accounts, real quotas, notification content, or local computer paths.

Requirements and Support Boundary

The current source targets:

• Apple Silicon Mac
• macOS 14 or later
• Xcode command-line tools with Swift 6.2 support
• a Codex executable that the user obtained and trusts
• an existing CODEX_HOME

Codex is not included. This project does not provide support for OpenAI accounts, sign-in, billing, or quota rules. Use the appropriate official support channel for those issues.

You must explicitly select a Codex executable in Settings. The app does not automatically search its bundle, inherited PATH, Homebrew, or common installation directories.

Source Code Only

This repository currently provides source code only. It does not provide an official .app, .dmg, or .zip for end users, and it does not claim that any local build has passed distribution signing or Apple notarization.

Scripts/build-development-app.sh creates a local development app. It uses an ad-hoc signature and a separate development identity. It is not distributable and must not be presented as an official release artifact.

If official downloads are offered in the future, obtain them only from a GitHub Release clearly identified by this repository, and verify the release notes, checksums, and signing status.

Build from Source

Run the tests from the repository root:

swift test --parallel

Build the development app:

Scripts/build-development-app.sh
open dist/development/CodexQuotaDev.app

The development script does not accept CODE_SIGN_IDENTITY. Its output is dist/development/CodexQuotaDev.app, with bundle identifier org.codexquota.monitor.dev. Its state directory and Keychain service are also isolated from the production identity.

This build is for local development and interface inspection. An ad-hoc signature is not suitable for distribution. A build opening on one Mac does not prove that it meets release, login-item, or long-term installation requirements.

Contributors must use synthetic tests. Automated tests do not need to read a real auth.json, state file, or Keychain and do not need to launch real Codex.

Usage

Select Codex and Home

After the first launch, right-click the floating panel and open Settings. Under Advanced, select the Codex executable. The confirmation screen displays only a safe file name and a short SHA-256 digest. A trust receipt proves only that the current bytes match the recorded file; it does not prove publisher identity, official origin, or absolute safety.

When CODEX_HOME is blank, the app first uses a non-empty CODEX_HOME from the launch environment and otherwise uses ~/.codex. Saving a new path stops the old sidecar before connecting with the new path.

Account Bindings and Markers

The first confirmed account binds to Account 1 and defaults to a blue δ. The next confirmed, different account binds to Account 2 and defaults to a red ε. These are stable mappings rather than temporary current/previous labels.

Each slot supports a Preset Symbol, Custom Text, and Custom Color. Custom Text is limited to 20 characters, and colors are saved as opaque solid values. Settings also provides Swap Account Markers, Restore Default Appearance, and Reset Account Bindings:

• Restore Default Appearance changes only the Settings draft; saving restores the default letter and color for that slot.
• Reset Account Bindings clears account mappings and quota snapshots while preserving configured appearance.
• A third account never overwrites an existing mapping automatically. The user must explicitly choose Replace Account 1 or Replace Account 2.

The persisted marker shape is accountMarkers → delta/epsilon → content(kind,value)+rgb. delta and epsilon are internal logical slot names only.

Floating Panel

• Moving the pointer into the panel expands it; leaving the complete panel collapses it.
• Clicking pins the expanded panel; clicking again unpins it.
• Dragging past the gesture threshold hands window movement to macOS. On release, the panel snaps to the left or right edge.
• The context menu provides Refresh Now, Swap Account Markers, Settings, movement commands, Restore Default Position, and Quit.

The compact size is 88 × 44 pt. With Reduce Transparency or Increase Contrast enabled, the app uses an opaque fallback appearance. With Reduce Motion enabled, the panel changes directly to its final size.

Live, Cached, and Alerts

Live means the quota has passed the current account identity, authentication file fingerprint, and sidecar connection-epoch gates. When accounts switch, the old number immediately leaves the live position. The other account shows only its last confirmed snapshot and timestamp.

Alerts are disabled by default. The app requests macOS notification permission only after the user enables the 20% / 10% alerts. Do not consume quota deliberately to test alerts; use synthetic data or wait for a natural threshold crossing.

Privacy and Security

The app reads up to 1 MiB of the complete auth.json under the effective Home, and those bytes briefly enter process memory. The decoded model reads only tokens.account_id; the code does not promise reliable zeroing of the original file bytes or account ID.

A non-empty account ID is processed with HMAC-SHA256 using a 32-byte random salt stored in Keychain. The result is encoded as 64 lowercase hexadecimal characters (256 bits). The production Keychain tuple is:

• service: org.codexquota.monitor.identity-salt
• account: account-hash-salt-v1

The production state file is ~/Library/Application Support/CodexQuota/state.json. Schema 3 persists account HMACs, quota snapshots, notification state, panel position, and preferences. It also stores custom executable and Home paths; trust receipt path/device/inode/size/times/SHA-256 values; and user-entered custom markers. Custom paths may contain the local user name, and custom markers are stored in plain text. Never use a credential as a marker.

The app launches the selected Codex subprocess with app-server --listen stdio:// and calls account/read and account/rateLimits/read. Codex Quota itself has no telemetry, cloud sync, or project-operated remote service, but the Codex subprocess may access the network.

The subprocess may inherit the planned proxy and certificate variables, including HTTP_PROXY, HTTPS_PROXY, SSL_CERT_FILE, and SSL_CERT_DIR. The app also sets CODEX_HOME, HOME, a fixed PATH, and TMPDIR. The environment allowlist is not a sandbox; the subprocess still runs with the current user's permissions.

See Privacy and Data Flow and Architecture Overview for details.

Known Limitations and Compatibility

• The current target is Apple Silicon with macOS 14 or later.
• The repository provides source only; the ad-hoc development app is not distributable.
• The app does not automatically locate Codex. The user must explicitly select and confirm a local file.
• File confirmation does not verify a publisher or official origin.
• Before launch, the app revalidates the path, file identity, and SHA-256 and holds a file-descriptor lease. The final posix_spawn still executes by path, so a residual same-user path-replacement race cannot be eliminated entirely.
• The Codex subprocess runs with current-user permissions, may read accessible resources outside the selected Home, and may use the network.
• Real protocol compatibility depends on the selected Codex. Missing methods, changed response shapes, timeouts, or connection closure can make the current connection unavailable.

This release-preparation run did not launch real Codex, so the project does not claim a supported Codex version range. A “last locally verified” record is evidence, not a support guarantee. See Codex Compatibility.

Uninstall and Remove Data

First disable Launch at Login in Settings, then Quit from the panel context menu. You can then move the installed app to the Trash.

Production data is stored in ~/Library/Application Support/CodexQuota. To remove it completely, move that directory to the Trash in Finder, then delete the production Keychain salt:

security delete-generic-password \
  -s org.codexquota.monitor.identity-salt \
  -a account-hash-salt-v1

Development data uses ~/Library/Application Support/CodexQuota-Dev and org.codexquota.monitor.dev.identity-salt, separate from production. Delete only entries that you have confirmed belong to this product.

Do not delete CODEX_HOME, ~/.codex, or its auth.json. Those belong to Codex, not to this utility.

Contributing, Support, and License

• MIT License
• Security Policy
• Contributing Guide
• Support Scope
• Architecture Overview
• Privacy and Data Flow
• Codex Compatibility

Before submitting an Issue or Pull Request, remove user names, host names, absolute paths, real accounts, quotas, and credentials. Report vulnerabilities privately through GitHub Security Advisories.