Local-first Codex quota tracking and account switching for macOS and Windows.
Website · GitHub · Releases · Security
CodexControl is a focused desktop app for people who actively manage multiple OpenAI Codex accounts.
It does two things well:
- shows live quota directly from OpenAI
- switches the active Codex account used by the local CLI
brew install --cask ademisler/tap/codexcontrol- macOS and Windows release: Latest GitHub release
- Homebrew tap: ademisler/homebrew-tap
Most tools around this workflow fall into one of these categories:
- multi-provider dashboards with too much surface area
- browser-driven quota trackers with extra runtime overhead
- scripts that estimate usage instead of reading the live account state
- switchers that do not tell you which account is actually usable right now
CodexControl is intentionally narrower:
- Codex-only
- local-first
- fast to scan
- built around real quota windows and active-account control
| Capability | What it does |
|---|---|
| Live quota reads | Fetches Codex quota windows directly from OpenAI using each account's local auth state |
| 5-hour and 7-day windows | Preserves per-window usage independently when both windows are available |
| Exact reset times | Shows when each quota window refills |
| Active account switching | Replaces the ambient ~/.codex session with the selected account and refreshes desktop state where required |
| Reauthentication | Refreshes a saved account without rebuilding the account list |
| Local account management | Add, remove, relabel, refresh, and open account folders from the app |
| Periodic refresh | Rechecks all accounts every 5 minutes |
- CodexControl reads each account from local Codex homes.
- It loads
auth.jsonfor that account and refreshes tokens when required. - It requests quota data directly from OpenAI.
- It keeps the account list sorted by practical usefulness, so usable accounts stay on top.
- When you switch accounts, it updates the ambient Codex session and restarts Codex Desktop to apply the new identity.
- On Windows, it also syncs Codex global state and preserves/restores Codex Desktop session state for the account being switched.
Quota accuracy is a first-order requirement in this project.
CodexControl uses these safeguards:
- cache-bypassing network sessions
- repeated live reads with equivalence checks
- rejection of inconsistent live responses
- per-window normalization that preserves the original OpenAI values
- stale snapshot clearing on refresh failures
This is especially important for Team and paid plans where the 5-hour window can be exhausted while the 7-day window still has remaining capacity.
CodexControl is local-first by design.
- account files stay on your machine
- the app reads local
auth.jsonfiles from Codex homes - the public repository does not ship real account data, snapshots, or tokens
- demo screenshots in this repository use synthetic accounts only
Current storage locations:
- macOS:
~/Library/Application Support/CodexControl - Windows:
%APPDATA%\\CodexControl
Migration from previous local app directories is automatic.
- Built with SwiftUI + AppKit
- Ships as a menu bar app
- Supports Codex Desktop restart after account switching
- Includes release scripts for signing and notarization when Apple credentials are available
- Lives under
windows - Uses Python with a tray-first workflow
- Includes add account, refresh, reauthenticate, switch, and install scripts
- Switches accounts by updating
auth.json, Codex global state, and the Codex Desktop MSIX session cache - Detailed switch fix notes live in
windows/ACCOUNT_SWITCH_FIX.md
The project website lives at codexcontrol.app.
- Static landing page source:
site - Cloudflare Pages config:
wrangler.jsonc - Deploy command:
./Scripts/deploy_site.sh - Homebrew cask:
ademisler/tap/codexcontrol
swift build
./Scripts/package_app.sh
open ./Build/CodexControl.apppython -m pip install -r .\windows\requirements.txt
python .\windows\CodexControlWindows.pywBuild a standalone EXE:
powershell -ExecutionPolicy Bypass -File .\windows\build.ps1Install the built EXE and register startup:
powershell -ExecutionPolicy Bypass -File .\windows\install.ps1 -EnableStartup -LaunchSources/CodexControl/ macOS app
Scripts/ macOS packaging helpers
Support/ app metadata
site/releases/ Release notes hosted on codexcontrol.app
site/ marketing website for codexcontrol.app
wrangler.jsonc Cloudflare Pages config
CHANGELOG.md release history
docs/releasing.md release process
windows/ Windows implementation and scripts
docs/images/ repository screenshots
Setup and contribution notes live in CONTRIBUTING.md.
Security reporting guidance lives in SECURITY.md.
MIT