Codexex

A native macOS menu bar utility with an iPhone and iPad companion for viewing Codex quota windows, reset timing, and local usage signals.

Website · Documentation · Privacy

Overview

Codexex is independent from OpenAI, Anthropic, and Apple. It shows the reported 5-hour quota window when one is available, with weekly allowance and reset timing alongside it, and falls back to weekly allowance and progress when an account reports no 5-hour window. Quota and forecast values are informational: they can be delayed, incomplete, rounded, unavailable, or different from the source of truth in your OpenAI account dashboard or invoices.

Features

• Compact macOS menu bar popup, Settings, onboarding, refresh controls, notifications, appearance choices, and launch-at-login support.
• Native iPhone and iPad quota views, Preview Mode, settings, and an optional Live Activity for the Lock Screen and Dynamic Island.
• Codex extra-usage credits alongside subscription quota on Mac and iOS, refreshed from the same signed-in response when a credit balance is reported.
• On-device quota history and forecast views.
• On macOS, reads official local Codex session logs to show token burn, project and model activity, cache-read pressure, tool-loop signals, and context-window pressure when the relevant data is present.
• First-use choice of ChatGPT subscription sign-in or OpenAI API access. Public API mode checks model access and organization Admin usage/cost reports. An optional unofficial credit-balance reader is disabled until the user accepts a warning about account restriction, suspension or ban risk. It is not an official or provider-approved method. Validated credentials stay in device-only Keychain storage; monitoring never generates content.
• ChatGPT sign-in through an OAuth device-code flow; the macOS app uses a bundled Rust helper behind a sandboxed XPC service.

Sign-in, token storage, quota requests, quota history, and local session analysis run on the device. Public API monitoring does not capture website sessions or import browser cookies. After explicit consent, optional unofficial billing sign-in uses its own persistent web view to observe the billing page's session authorization; it does not import an existing browser's cookies or inspect password fields. Codexex does not send OpenAI credentials, account identity, quota values, or usage history to a Magrathean account service. See the privacy notice for the full picture, including the optional iOS Live Activity wake path.

Getting started

Run commands from the repository root:

swift test
cargo test --manifest-path Helper/CodexexHelper/Cargo.toml
xcodegen generate --spec project.yml

See the runbook for the full build loop, release checks, and the helper/XPC flow.

Repository map

• Sources/CodexMeterCore/ contains shared quota models, formatting, local usage parsing, and service contracts.
• Sources/CodexMeterApp/ contains the macOS menu bar app, onboarding, Settings, history, and local diagnostics.
• Sources/CodexMeteriOS/ contains the iPhone and iPad app.
• Sources/CodexMeterWidgets/ contains small/medium Home Screen quota and API-balance widgets plus Live Activity presentation.

Home Screen widgets share only display values and observation timestamps through group.com.magrathean.CodexexApp; credentials remain in the app. They update after app refreshes and request background refresh when installed, independently of Live Activity. iOS controls when those background requests run. Timelines mark old observations stale after 30 minutes or a quota reset and never invent a new balance. Tap a widget to open the app and refresh. Enable the matching App Group for both app and extension when provisioning a signed device build. API keys and billing sessions currently require an unlocked phone. If a refresh cannot read those credentials, widgets retain the last observed balance with its original timestamp and a stale label; they do not treat it as a fresh check.

• Sources/CodexexXPCService/ contains the sandbox bridge to the helper.
• Helper/CodexexHelper/ contains the Rust authentication and quota helper.
• Scripts/ contains helper packaging and optional local companion scripts.
• Tests/ contains Swift and XPC tests.
• project.yml is the Xcode project source of truth. Package.swift is the Swift Package Manager adapter for local package tests.
• fastlane/metadata/ contains App Store metadata inputs.

Optional local companions

The status script inspects local Codex session data. The optional installer writes lifecycle hooks at the user level:

Scripts/codexex-status.sh
Scripts/install-codexex-companions.sh

The installer backs up an existing hooks file and backs up the user configuration when it needs to enable Codex hooks. It replaces entries for the four named lifecycle events it manages. Review the resulting user-level configuration before relying on the hooks; the runbook describes the changes. Hook metadata can still contain private paths and identifiers.

Documentation

• docs/index.md — documentation index.
• AGENTS.md — project boundaries and source-backed development rules.
• .github/CONTRIBUTING.md — contribution workflow.
• .github/SUPPORT.md — support requests and useful diagnostic material.
• .github/SECURITY.md — vulnerability reporting and safe-harbour boundaries.
• PRIVACY.md — local data, network communication, and the optional wake service.

Licence

Codexex is proprietary; all rights reserved. See LICENSE and NOTICE.

_{© 2026 MAGRATHEAN UK LTD · Legal}