A modern, privacy-first Android client to monitor real-time OpenAI Codex and ChatGPT Plus/Team quotas, rate limits, and subscription renewal schedules across multiple accounts.
-3DDC84?style=for-the-badge&logo=android&logoColor=white){kind=icon}
- Dual Quota Windows: View simultaneous Weekly and 5-hour rolling quota windows with independent remaining/used gauges for ChatGPT Plus, Team, and Enterprise accounts.
- Independent Reset Countdowns: Real-time rollover timers for each quota window (e.g.,
4d 12h,2h 15m). - Weekly Ideal-Pace Guidance: Visual pacing indicators (Ahead of ideal pace, On ideal pace, Behind ideal pace) calculated from weekly remaining capacity and time to reset.
- Granular 5-Hour Alert Controls: Choose whether low-quota notifications apply only to weekly limits (default) or extend to 5-hour rolling windows via Settings.
- Separate Alert Deduplication: Independent milestone tracking per window prevents duplicate alert notifications across rolling reset cycles.
- Polished Material 3 Dashboard: Refined account cards and detail views make weekly pacing and both quota windows easier to scan.
- What's New in v1.2.0
- Key Features
- Security & Privacy
- Download & Installation
- Architecture & Technology Stack
- Building from Source
- Legal Disclaimer
- License
- Simultaneous Rolling Windows: Tracks both Weekly (primary 7-day window) and 5-hour (secondary rolling window) quota capacities on active subscriber accounts when provided by OpenAI's usage endpoints.
- Independent Countdown Timers: Real-time countdowns indicating the exact duration until each window rolls over (e.g.,
5d 4h,1h 30m,45m). - Banked Reset Tracking: Displays available banked usage-limit resets along with next expiration timestamps when returned in the usage payload.
- Platform API Rate Limits: For developer API-key accounts, monitors Requests Per Minute (RPM) and Tokens Per Minute (TPM) against tier limits with dedicated visual meters.
To assist with budgeting capacity across the 7-day cycle, Codex Quota compares current remaining weekly capacity against an ideal linear consumption curve:
| Pacing Status | Condition | Meaning |
|---|---|---|
| Ahead of ideal pace | Actual remaining is more than 5 percentage points above ideal | Quota is being consumed slower than the linear guide; surplus capacity remains. |
| On ideal pace | Actual remaining is within 5 percentage points of ideal | Usage aligns closely with the linear weekly guide. |
| Behind ideal pace | Actual remaining is more than 5 percentage points below ideal | Quota is being consumed faster than the linear guide; it may reach the limit before reset. |
How Pacing Works: Ideal remaining capacity is calculated linearly from the time remaining until reset:
$$\text{Ideal Remaining %} = \left(\frac{\text{Time Until Reset}}{\text{7 Days}}\right) \times 100$$ Note: This pacing indicator is a reference guide for linear planning based on current percentage and reset time. It does not measure historical token logs or guarantee future availability.
- WorkManager Background Sync: Configurable periodic background sync (15 min, 30 min, 1 hr, 3 hr, 6 hr) with automatic network retry constraints.
- Multi-Threshold Quota Alerts: Receive Android notifications when remaining quota drops below selected milestone thresholds (≤5%, ≤10%, ≤25%).
- Optional 5-Hour Alerts: Weekly quota is monitored by default; toggle "Include 5-hour quota warnings" in Settings to monitor short-term burst limits too.
- Per-Window Deduplication: Milestone alerts fire once as quota enters a lower threshold and reset when capacity recovers above configured limits, tracking weekly and 5-hour windows independently.
- Signed-Out Detection: Sends an alert after a background refresh detects that authentication tokens expired or became invalid.
- OAuth 2.0 Device Code Authorization: Sign in using standard OAuth device authorization (
https://auth.openai.com/codex/device) with PKCE token exchange. No raw secret entry required. - Platform API Key Support: Add direct API keys for standard developer endpoints.
- Multi-Account Organization: Custom account nicknames, plan badges (Plus, Team, Enterprise, API), and custom accent color indicators.
- Subscription Renewal Tracking: Configurable renewal dates and countdowns to monitor monthly/yearly billing cycles alongside live quotas.
- Jetpack Compose & Material You: Adaptive dynamic color palette support, light/dark theme switching, and smooth edge-to-edge layout.
- Jetpack Glance Widgets:
- Small (2x2): Circular gauge, remaining percentage, and reset timer.
- Medium (4x2 / 4x1): Responsive card with primary quota bar, reset countdown, secondary 5-hour badge, and auto-adapting 1-row compact mode.
- Multi-Account (4x3 / 4x4): Monitor up to 5 accounts simultaneously with status indicators and individual quota levels.
- Custom Widget Themes: Choose between Codex Dark (obsidian) and Material You dynamic themes.
Codex Quota is built with a privacy-first, on-device architecture:
| Aspect | Implementation Details |
|---|---|
| Hardware Keystore Encryption | API keys and OAuth tokens are encrypted on-device with AES-256-GCM using cryptographic keys from the Android Keystore system. |
| Direct Communication | All HTTPS requests communicate directly with OpenAI authentication and API endpoints (auth.openai.com, api.openai.com, chatgpt.com) with no intermediate proxy servers. |
| Zero Telemetry & Tracking | No analytics frameworks, crash trackers, advertising identifiers, or user tracking. |
| Backup Protection | Sensitive credential storage files are explicitly excluded from Android cloud backup and device transfer rules (backup_rules.xml and data_extraction_rules.xml). |
Download the latest release APK directly from GitHub Releases:
👉 Download Latest APK (GitHub Releases)
- Download
codex-quota-vX.X.X.apkonto your Android device (requires Android 8.0+ / API 26+). - Open the downloaded file to install (allow "Install unknown apps" if prompted).
- Launch Codex Quotas and tap + to add your first account.
One-Time Signing Migration Note: If upgrading from an older debug-signed APK, uninstall that build once before installing the production-signed release. Subsequent releases signed with the production certificate can update directly without uninstalling.
Codex Quota follows modern Android architecture and clean separation-of-concerns practices:
app/
├── auth/ # OAuth 2.0 PKCE device authorization & JWT parsing
├── data/
│ ├── local/ # Room database, Encrypted SharedPreferences, Preferences DataStore
│ └── remote/ # OkHttp client, Kotlinx Serialization, OpenAI usage endpoints
├── domain/ # Domain entities, use cases, pacing evaluator, repository contracts
├── notifications/ # Quota threshold & auth state notification managers
├── security/ # Android Keystore Manager & AES-256-GCM credential store
├── ui/
│ ├── components/# Circular gauges, linear quota bars, pacing badges, metric cards
│ ├── feature/ # Dashboard, Account Detail, Add Account, Settings, About, Onboarding
│ ├── navigation/# Jetpack Compose type-safe navigation
│ └── theme/ # Material Design 3 color schemes, typography, dynamic theming
├── widget/ # Jetpack Glance widgets (Small, Medium, Multi-Account) & config
└── worker/ # AndroidX WorkManager periodic background synchronization
- Language & Coroutines: Kotlin 2.0.21, Coroutines & Flow (JVM Target 17)
- UI Framework: Jetpack Compose (BOM 2024.11.00) with Material Design 3
- Local Persistence: Room SQLite 2.6.1 + Preferences DataStore 1.1.1
- Security: Android Keystore + AndroidX Security Crypto (AES-256-GCM)
- Background Tasks: AndroidX WorkManager 2.10.0
- Home Widgets: Jetpack Glance 1.1.1
- Networking: Square OkHttp 4.12.0 + Kotlinx Serialization JSON 1.7.3
- JDK: Java Development Kit 17 or 21
- Android Studio: Ladybug (2024.2.1+) or Gradle 8.11+
- Android SDK: Platform API 35 (Compile SDK 35, Min SDK 26, Target SDK 35)
# Clone the repository
git clone https://github.com/boudywho/codex-quota-android.git
cd codex-quota-android
# Run unit tests
./gradlew test
# Assemble Debug APK
./gradlew assembleDebug
# Output APK location:
# app/build/outputs/apk/debug/app-debug.apkDebug builds and unit tests do not require release signing credentials.
Release APKs must be signed with a production certificate. Create a signing.properties file in the repository root (this file is git-ignored; do not commit keys or passwords):
storeFile=path/to/release.keystore
storePassword=your-store-password
keyAlias=your-key-alias
keyPassword=your-key-passwordstoreFile can be specified as an absolute path or a path relative to the project root. Each property can also be set via environment variables:
signing.properties Key |
Environment Variable |
|---|---|
storeFile |
ANDROID_KEYSTORE_FILE |
storePassword |
ANDROID_KEYSTORE_PASSWORD |
keyAlias |
ANDROID_KEY_ALIAS |
keyPassword |
ANDROID_KEY_PASSWORD |
Build a production APK with:
./gradlew assembleReleaseThe build configuration executes a validateReleaseSigning verification task that fails with a descriptive error if signing credentials or the keystore file are missing, preventing unauthenticated fallback to debug certificates.
GitHub Actions runs unit tests, Android lint, and a debug APK build on pulls and pushes to main. Tagged releases require the following GitHub Actions secrets:
ANDROID_KEYSTORE_BASE64: Base64-encoded production keystoreANDROID_KEYSTORE_PASSWORD: Keystore passwordANDROID_KEY_ALIAS: Key aliasANDROID_KEY_PASSWORD: Key password
To publish a release:
- Update
versionNameandversionCodeinapp/build.gradle.kts. - Push a matching Git tag (e.g.,
v1.2.0forversionName = "1.2.0"). - The tag workflow verifies version alignment, decodes the keystore temporarily in the runner environment, compiles the signed release APK, and attaches
codex-quota-vX.X.X.apkto the GitHub Release.
Codex Quota is an independent open-source project developed for developers and power users to monitor personal API usage and subscription windows.
- This application is not created, affiliated with, authorized, maintained, sponsored, or endorsed by OpenAI, Inc.
- OpenAI, ChatGPT, Codex, and GPT are trademarks or registered trademarks of OpenAI, Inc.
Distributed under the MIT License. See LICENSE for more information.