Codexex

Codexex is a macOS menu bar app with an iPhone/iPad companion for viewing Codex quota state, reset windows, history, and forecast.

Built by Magrathean UK.

Canonical docs

• AGENTS.md
• RUNBOOK.md
• PRIVACY.md

Current release: 5.1.1 (16). project.yml is the version and target source of truth.

Product shape

• Menu bar first on macOS. No dock-facing main window.
• Native iPhone/iPad companion using the shared quota contracts.
• SwiftUI app content with a small AppKit shell for status item behavior.
• 5H, weekly, and 30-day history views, reset times, local history, and forecast.
• Local Codex session usage: project/model/session burn, cache-read pressure, tool-loop and model-overkill signals.
• Companion scripts for local status JSON and Codex lifecycle hook capture.
• System, Light, and Dark appearance modes that follow the same app theme in popup and Settings.
• ChatGPT sign-in plus Preview Mode for offline review.
• Sandboxed app with a bundled helper and XPC bridge.

Repo layout

• Sources/CodexMeterCore/: quota models, formatting, binary discovery, and service contracts.
• Sources/CodexMeterApp/: app lifecycle, menu bar model, popup, settings, onboarding, and history UI.
• Sources/CodexMeteriOS/: iPhone/iPad app shell, onboarding, settings, and quota presentation.
• Sources/CodexexXPCService/: XPC service that brokers the helper process.
• Helper/CodexexHelper/: Rust helper used for the OAuth device-code flow and quota reads.
• Scripts/: helper build and embed scripts used by the Xcode target.
• AppStore/: entitlements and App Store-facing bundle settings.
• Tests/: XCTest coverage for both core logic and app behavior.
• fastlane/metadata/: checked-in App Store text inputs.
• .codex/hooks.json: trusted project-local Codex guard for generated Xcode files.
• Package.swift: SwiftPM adapter for local development and package tests; project.yml remains the Xcode source of truth.

Quick start

Local build and test commands are self-contained. Xcode examples use /tmp cache paths so they do not depend on files outside this checkout.

swift test
xcodegen generate --spec project.yml
xcodebuild -project CodexMeter.xcodeproj \
  -scheme CodexMeterApp \
  -derivedDataPath /tmp/codexex-derived-data \
  -clonedSourcePackagesDirPath /tmp/codexex-swiftpm-cache \
  build

Useful checks:

cargo test --manifest-path Helper/CodexexHelper/Cargo.toml
bash Scripts/check-codexex-companions.sh
bash Scripts/release-smoke.sh

Use RUNBOOK.md for helper flow, XPC notes, and release hygiene.

Legal

Copyright © 2026 Magrathean UK Ltd. All rights reserved.

Codexex is proprietary software. See LICENSE for the full licence text. Third-party components and their licences are listed in license.md. Apache-2.0 attribution required by the openai/codex Rust crates and other upstream components is recorded in NOTICE. Public availability of this repository does not grant any right to copy, modify, redistribute, or use the Codexex source outside the licence terms.

The published Codexex application (macOS & iOS) is governed by the user-facing terms published at:

• Privacy Policy — https://codexex.eu/privacy/
• Terms of Service — https://codexex.eu/terms/

Quota information is informational only

Quota readings, reset timing, history, session-burn analytics, and forecast values shown by Codexex are derived from third-party API responses (notably from OpenAI) and from local computation. They may be incomplete, delayed, inaccurate, rounded, cached, or unavailable for reasons outside our control. Codexex is not a billing system, an audit log, or a contractual record and is not a substitute for the source of truth provided by your OpenAI account dashboard or invoices.

Trademarks and disclaimers

OpenAI, ChatGPT, GPT, Codex, and Spark are trademarks of OpenAI, Inc. or its affiliates. Anthropic and Claude are trademarks of Anthropic, PBC. Apple, the Apple logo, macOS, iPadOS, iOS, and Swift are trademarks of Apple Inc.

Codexex is not affiliated with, endorsed by, sponsored by, authorised by, or in any way officially connected to OpenAI, Anthropic, or Apple. References to these names exist solely for descriptive interoperability. All trademarks remain the property of their respective owners.

Reporting

For security issues, see SECURITY.md. For licensing or commercial enquiries, email contact@magrathean.uk.

---

Magrathean UK Ltd. is a company registered in England and Wales (Company No. 16955343) with registered office at 16 Caledonian Court West Street, Watford, England, WD17 1RY.