English README | 中文说明
CodexAuth Switch is a local Windows and macOS desktop utility for quickly switching between multiple Codex App login accounts.
It is designed for people who use more than one OpenAI / Codex App account. Start official sign-in from the panel or save the current login, then switch accounts. Credentials are encrypted locally and usage statistics come from local logs. Windows active-account quota comes through Codex; standby quota and token renewal use direct requests to fixed OpenAI endpoints. Credentials and conversation history are never uploaded to the project author or third parties.
One-line positioning: CodexAuth Switch is a local-first Codex App multi-account switcher with auth.json snapshot management, Windows DPAPI / macOS Keychain encryption, quota display, and token usage statistics.
This is an unofficial project and is not affiliated with OpenAI.
Latest: v0.1.37 · Release notes · Issues
v0.1.37 fixes stretched and clipped icons in GitHub installers and adds rendering and artifact checks across display scales. It retains official sign-in without logging out, quota recovery, Business fallback selection, local usage statistics, email hiding, and sidebar update links.
- Users who manage multiple Codex App login accounts on Windows or macOS.
- Users who want to switch the active OpenAI Codex / Codex App account quickly.
- Users who want to safely save and restore local
~/.codex/auth.jsonlogin snapshots. - Users who want to view local session quota, weekly quota, remaining resets, token usage, and project/model statistics.
- Users who want local usage statistics and a live quota check before switching to a standby account.
Codex account switcher, Codex multi account, Codex App account manager, OpenAI Codex account switcher, Codex auth.json switcher, Codex local login manager, Codex quota viewer, Codex token usage dashboard, Codex Windows macOS desktop app, Codex DPAPI Keychain encryption, Codex local quota estimate, Codex local quota tracking, Codex local history read-only.
- Sign-in and account management: official browser authentication from the panel, automatic encrypted import without logging out, existing-login import, account names and switching.
- Credential protection and migration: Windows DPAPI / macOS Keychain snapshots, backups before changes, password-encrypted
.codexauthimport/export, and stale-credential warnings. - Automatic recovery (Windows, opt-in): native quota-failure detection, a cancellable 15-second countdown, idle-task and live-quota checks, and continuation of eligible tasks and goals.
- Account selection: Plus, five-hour Business, then weekly-only Business; skip unreset windows with at most 2% remaining, and try Business with unknown quota last.
- Local quota and usage: quota windows, reset counts, project/model statistics, incremental log reads and shared refreshes. Data timestamps and scopes are explicit; local totals are not official lifetime totals.
- Widget and privacy display: main window, tray and quick-switch widget; hide emails in the quota overview and expand credential-storage or compatibility details.
- Project links: GitHub icon, actual app version, manual update checks and developer WeChat QR code.
Automatic task recovery is Windows-only. macOS supports account management, quota, usage and credential migration; native macOS sign-in, Keychain and GUI behavior still require end-to-end testing.
| Main Window | Floating Quick View |
|---|---|
 |
 |
CodexAuth Switch is intentionally scoped to the local Codex login file and the app's own storage directory.
~/.codex/auth.json- The active local login file used by Codex App.
- During account switching, the app replaces this file with a saved account snapshot.
~/.codex/config.toml- Ensures the top-level setting contains
cli_auth_credentials_store = "file"so current Codex releases continue using switchableauth.jsoncredentials. - Creates a timestamped
config.toml.codexauth-backup-*copy in the same directory before changing the file.
- Ensures the top-level setting contains
- App account metadata:
%APPDATA%\codex-auth-switcher\accounts.jsonon Windows;~/Library/Application Support/codex-auth-switcher/accounts.jsonon macOS. - Encrypted account snapshots:
%APPDATA%\codex-auth-switcher\accounts\*.dpapion Windows;~/Library/Application Support/codex-auth-switcher/accounts/*.keychainon macOS. - Encrypted backups created before operating on the active account:
%APPDATA%\codex-auth-switcher\backups\*.dpapion Windows;~/Library/Application Support/codex-auth-switcher/backups/*.keychainon macOS.
~/.codex/auth.json- Used to import the current login and identify the account.
~/.codex/sessions/**/rollout-*.jsonl- Used for local usage and quota snapshot calculation.
~/.codex/session_index.jsonl- Used to enrich local session metadata when available.
~/.codex/logs_2.sqlite- Opened in read-only mode to read local Codex quota events.
- It does not directly rewrite existing conversation logs; opt-in recovery lets Codex receive continuation messages and append normal task records.
- It does not delete
~/.codex/sessions. - It does not write to
logs_2.sqlite. - It does not upload credentials, account data, logs or usage to the project author or third parties. User-triggered official sign-in and continuation communicate with OpenAI through Codex.
- Codex owns active-account quota reads and renewal; updated
auth.jsoncontents are synchronized into encrypted snapshots. - Standby access tokens and workspace IDs go only to
https://chatgpt.com/backend-api/wham/usage; refresh credentials go only tohttps://auth.openai.com/oauth/token. No conversation or usage logs are sent, and redirects are refused.
Features that intentionally affect Codex App runtime state include account switching, reauth, deleting the active account, restarting Codex App, and opt-in automatic switching and continuation. These actions may update config.toml, replace or remove the current auth.json, and restart Codex App so the new local login state takes effect. Automatic continuation also asks the local Codex interface to verify the active account's quota and send a continuation prompt; Codex itself performs the associated service requests.
When importing the current login, the app reads ~/.codex/auth.json and validates that it matches Codex App's ChatGPT login format.
It parses JWT payloads locally and extracts fields such as email, user ID, and workspace/account ID. Account matching does not rely on a single claim. It combines personal identity and workspace identity when possible, because one person can belong to multiple workspaces and one workspace can contain multiple users.
Saved account snapshots are encrypted with Windows DPAPI or Electron safeStorage backed by macOS Keychain. During panel sign-in, the official helper temporarily stores plaintext auth.json under login-sessions/login-* in the app data directory. These files are removed after import, cancellation or failure; the next app launch retries cleanup of leftovers.
Windows uses DataProtectionScope.CurrentUser; macOS uses the current user's Keychain.
This binds encrypted snapshots to the current operating-system user. Other users, machines, or operating systems cannot directly decrypt them.
Saved account snapshots are stored in:
- Windows:
%APPDATA%\codex-auth-switcher\accounts - macOS:
~/Library/Application Support/codex-auth-switcher/accounts
Backups created before operating on the active login are stored in:
- Windows:
%APPDATA%\codex-auth-switcher\backups - macOS:
~/Library/Application Support/codex-auth-switcher/backups
Codex renews the active account, and CodexAuth watches and encrypts the latest auth.json. Standby credentials renew only during a manual quota refresh or pre-switch check, when the access token expires within five minutes, or the last renewal is older than seven days or unknown. A quota HTTP 401 permits one renewal and retry. Renewal shares the account-mutation queue with switching, importing and deletion. Replacement credentials are atomically encrypted before further queries or mutations; failed writes retain the pending replacement, block account changes and are retried before exit.
Renewal does not guarantee a permanent login. Definitively expired, revoked or reused refresh tokens require sign-in again; network errors and rate limits retain credentials and back off. There is no background renewal without a quota check, so accounts left unused for a long time may need to sign in again. Separate sign-ins per machine are recommended because concurrent refresh-token rotation on different machines can invalidate saved copies.
The newest 60 encrypted backups are retained. Atomic-write temporary files older than one hour are cleaned at startup so long-running switching and usage tracking do not create unbounded cache growth.
When switching accounts, the app:
- Decrypts and validates the target snapshot and identity.
- Stops the desktop and its app-server when restart is enabled, or requires clients to be closed first. A running independent CLI blocks switching.
- Reads the final old credential, saves it, and creates an encrypted backup; backup failure blocks replacement.
- Rechecks client shutdown and target identity, then atomically replaces
auth.jsonthrough a temporary file. - Reads back the identity, updates saved account metadata and starts Codex if enabled.
The temporary-file plus atomic-rename approach reduces the chance that Codex App reads a partially written auth.json.
On Windows, restart stops the desktop process group belonging to the Codex installation. On macOS, it detects the current ChatGPT or legacy Codex application process, waits for it to exit, and relaunches it through Launch Services.
If a saved account's refresh token becomes invalid, the app can start a reauth flow:
- Stop the desktop and its app-server and verify no other Codex clients remain.
- Encrypt a backup of the final
auth.json, then remove the current login; stop if backup fails. - Start Codex App.
- Let the user complete the official login flow inside Codex App.
- After Codex App writes a fresh
auth.json, CodexAuth Switch watches for it and saves it back to the matching account.
This does not bypass or replace official login. The real login still happens inside Codex App.
The optional recovery toggle is off by default. Every 15 seconds it checks local tasks for explicit new quota failures or goals in usageLimited. A nearly empty widget estimate alone does not trigger switching.
Candidates are grouped as Plus, Business with a five-hour limit, weekly-only Business, Business with unknown windows, then other plans. Within a group, the nearest reset comes first, with remaining balance breaking ties. Missing records can be checked online; reauthentication flags and known unreset exhaustion exclude accounts. Live availability is required before the cancellable countdown and queried again afterward, before closing Codex. Unknown or failed checks keep the current account. All returned model pools are retained and checked conservatively: a pool with 2% or less remaining or incomplete data blocks automatic switching. A passed reset is not proof of replenishment. Other work must finish first, and target identity and availability are still verified through Codex after switching. Goal objective, budget and accounting are preserved.
This continues existing context rather than restoring process state. Manual account operations cancel pending recovery; uncertain sends are never replayed. Recovery tries to open the first confirmed task once. Requires a compatible Windows desktop interface and never automatically consumes reset credits.
On Windows, active-account quota is read through Codex every 30 seconds, with local logs and timestamped snapshots as fallback. Other platforms retain local reads for the active account. Standby accounts are queried only on manual refresh or before automatic switching, with renewal when needed; there are no startup or periodic batch queries. Closing Codex therefore leaves no standby polling requests, while manual refresh remains available in expanded account details. Requests share a one-minute cache, deduplicate concurrent reads and back off on failure. The post-countdown query bypasses the success cache. Quota sources use consistent online snapshot, local snapshot and local cache labels. Failed checks preserve the last successful snapshot and its timestamp, with an error; an old snapshot never authorizes automatic switching.
The automatic-switch settings include an opt-in weekly reset fallback, disabled by default. The old Business-only toggle does not automatically authorize the expanded Plus scope. Ordinary usable accounts are tried first. When none can be confirmed usable, standby accounts with freshly confirmed 100% weekly usage and available reset credit are tried in this order: Plus, Team / Business with a 5-hour limit, then weekly-only Team / Business. An exhausted 5-hour window with weekly quota remaining never authorizes redemption. Missing or unknown weekly quota, the 2% switching threshold, and an exhausted additional model pool alone also never authorize redemption.
Card details are read only when reset fallback is needed. The plan priority above is preserved; accounts within the same group are ranked by their earliest-expiring eligible full reset, with known expiration before an unspecified date and stable account-ID order for ties. Expired or malformed dates are excluded. Each account also uses its earliest eligible card. Details have a one-minute cache and failure backoff, with no periodic polling.
The cancellable 15-second warning identifies the one-credit redemption. Quota and card details are fetched fresh afterward; if the selected card or expiration changes, selection and countdown must run again instead of silently spending a different card. After checking idle tasks, the original failure, identity, settings and expiration, the selected card is redeemed. Switching requires a fresh successful quota check afterward. Account, credit and idempotency identifiers are persisted before POST. An uncertain result or quota that remains unavailable pauses further automatic redemptions across restarts, without retrying POST or spending another card. Check Codex Usage and refresh that account to confirm recovery. The same exhaustion window cannot be redeemed twice.
According to OpenAI's reset documentation, a full reset changes the weekly reset date. Requests use the machine's current network route; there is no per-account IP isolation or new periodic polling. Redemption requires a running Codex recovery flow. The signed-in account remains managed by Codex; this feature redeems only standby Plus / Business accounts. Tokens are sent only to the fixed official wham/rate-limit-reset-credits and /consume endpoints on https://chatgpt.com/backend-api/.
The all-account overview includes a refresh-all button with progress and success counts. It queries the active account through Codex and standby accounts online, bypassing successful snapshot caches while respecting failure backoff. Individual failures do not stop the batch; affected cards retain the previous snapshot and show the reason.
Successive official snapshots calibrate estimates between queries for the active account. Samples are isolated by account, plan, pool, window duration, model and service tier, and retained for seven days. Training requires at least a two-percentage-point change attributable to local records; prediction requires three stable samples with similar input/output and cache proportions. Actual official percentages remain intact, estimates are labeled, and each new official reading replaces the forecast. Missing logs, mixed-model training intervals, counter rollbacks, account-switch boundaries and reset crossings do not train the model. Predictions stop after two minutes without a fresh official snapshot or when the projected increment exceeds five percentage points. Usage from other devices cannot be fully attributed locally, so this remains a conservative estimate. Automatic switching still uses actual quota only.
When logs omit the speed tier, samples are restricted to the same thread and turn. Missing metadata is never treated as the default tier or reused across turns.
Usage increments used for training or prediction must lie entirely after the corresponding official snapshot. Crossing intervals, unknown starts and reversed timestamps retain the official value; older calibration samples are rebuilt. Malformed quota windows remain unknown and block automatic switching even when another window is valid.
Local estimate mode reads:
codex.rate_limitsrecords in session JSONL files.codex.rate_limitsand usage-limit records in the latest automatically discoveredlogs_N.sqlite.token_countevents in session files.- Complete log events, cached by file size and modification time and deduplicated across files. Account metadata stores quota snapshots and calibration samples isolated by model and service tier. The legacy
local-token-ledger.jsonno longer participates in statistics.
The app watches local log file changes with a short debounce and uses a low-frequency SQLite modification-time polling fallback to avoid missed filesystem events.
Quota snapshots are saved only into this app's own account metadata. They are not written back to Codex log files.
Multi-account statistics use the most recent account-switch time as their boundary. A session that continues across a switch is attributed through adjacent token-snapshot deltas, and quota calibration combines only post-switch events with that account's own saved learning so same-plan accounts do not leak into each other.
Quota details show used and remaining percentages and reset times, with estimates marked as approximate. The interface does not rate consumption pace or predict whether quota will run out early.
Electron windows use these security settings:
contextIsolation: true
nodeIntegration: false
sandbox: true
webSecurity: trueThe page CSP disables network connections:
connect-src 'none'The main process also installs an Electron webRequest.onBeforeRequest guard that cancels outbound requests for:
http://
https://
ws://
wss://
Renderer pages remain offline and receive no credentials or network access. The main process queries standby quota and renews credentials at fixed official HTTPS endpoints, and delegates active-account quota reads to Codex. Saved online results are bound to the account identity and encrypted credential version.
User-triggered update checks also use separate main-process HTTPS requests to this repository's fixed public GitHub endpoint. Only matching installer links within this repository are accepted and opened in the system browser. GitHub login data and Codex credentials are not read.
User-triggered account sign-in also connects to OpenAI authentication services through the system browser and an isolated official Codex helper, using the official local callback. Renderer pages remain offline.
npm installnpm startHidden local debug start on Windows:
npm run dev:hidden- Install Codex desktop and open CodexAuth Switch.
- Click “添加账号” (Add account), then “登录新账号” (Sign in to a new account).
- Select the desired account on the official page and complete authentication.
- The encrypted account is added automatically; the active Codex login stays unchanged.
- Repeat to add more accounts, or choose “保存当前登录” (Save current login) in the same dialog. Credential file import is available in the panel's More menu.
If the browser selects an existing account automatically, choose the intended account on the official page. Pending sign-in can be cancelled or reopened and times out after five minutes.
- Select a saved account in CodexAuth Switch.
- Check the five-hour and weekly quota in the account row, then click Switch. Expand the row for reset times and details.
- Enable restart to stop and relaunch Codex automatically; otherwise close Codex App and CLI before switching, then start Codex manually.
The app pins current Codex releases to file-backed credentials and fully restarts the desktop app when “restart after switch” is enabled, so the selected account takes effect after relaunch.
Use reauth when Codex reports that a refresh token can no longer be refreshed, or when a saved account has become stale.
Stale accounts show a Reauth button directly; other accounts offer it in the row's More menu. Automatic switching, reset credits and restart after switching are managed in Settings at the top of the panel.
The Usage page separates current account quota from local token statistics. Current session covers local records since the active account took effect; All local includes local history. Expand the statistics explanation for scope details.
The app clears the current local login and restarts Codex App. You then complete the official login inside Codex App. After Codex writes a new auth.json, CodexAuth Switch captures and saves it.
npm run lintnpm run local-data:validateThis command uses isolated fixtures to validate token deltas, duplicates and forks, account boundaries, quota pools, weekly windows, reset-credit provenance, calibration and account recovery. quota:validate remains a historical replay of the old price-weighted algorithm, not validation of the current algorithm.
npm run account-login:validate
npm run account-safety:validate
npm run auto-recovery:validateThese checks use fake credentials and isolated directories, without real account switching. Both Windows and macOS release jobs run the complete release checks.
npm run pack:winRun this command on macOS:
npm run pack:macIt creates DMGs for Intel (x64) and Apple Silicon (arm64).
The installers are written to:
release/
The release directory is a local build artifact and is not committed to Git by default.
src/main.js Electron main process, local file access, account switching, quota logic
src/preload.js Safe IPC bridge
src/ui/index.html Main window page
src/ui/app.js Main window renderer logic
src/ui/widget.html Floating quick-view widget page
src/ui/widget.js Floating widget renderer logic
scripts/generate-icon.js Local icon generation
scripts/start-dev-hidden.ps1 Hidden debug start script
scripts/validate-quota-estimate.js Quota replay validation script
QUOTA-LOGIC.md Quota-estimation notes
- Windows and macOS are supported; Linux is not currently supported.
- Encrypted snapshots are bound to the current system user and cannot be copied directly across machines or platforms.
- This targets Codex App local login switching, not Codex CLI-only workflows.
- Local estimate mode is a best-effort interpretation of local logs.
- Quota snapshots may stay stale until Codex writes new local rate-limit records.
- Do not share saved credential snapshots across machines or operating-system users.
Windows installers and Intel / Apple Silicon macOS DMGs are uploaded through GitHub Releases. The current builds are not commercially code-signed or Apple-notarized, so the operating system may show a security warning.
MIT License. See LICENSE.
Only save and switch accounts that you own or are authorized to use. Do not share auth.json, encrypted snapshots, or backup files with other people.
Expand historical development notes (current feature documentation takes precedence)
The sidebar developer link now opens https://ryanlin.me/assets/contact/wechat-qr.png in the system browser and is labeled “开发者微信” (Developer WeChat).
Below local diagnostics, the sidebar now shows a GitHub icon and project link, the running app version, an update-check button and developer Ryan Lin's website. Links open this repository or https://ryanlin.me in the system browser. Version text comes from the app. Header and sidebar share the existing update check and display newer-release, up-to-date, newer-local-build or failure status; network access remains user-triggered.
Automatic recovery skips an account when any quota window has 2% or less remaining and has not reached a valid reset time. An unknown reset time does not lift this restriction. A passed reset can make that window eligible again, subject to other windows and live verification. This threshold is a selection rule, not proof of official exhaustion.
Existing plan priority is unchanged. Business accounts (including team) with missing or unknown quota are attempted only after recorded candidates are unavailable; unknown quota is never treated as 100%. A known low window cannot become a fallback because another window is missing. Reauthentication requirements, exhaustion cooldown and the seven-day limit for recorded snapshots remain in place.
Each attempt retains the cancellable countdown, idle checks and live identity/quota verification before continuation. All unavailable candidates lead to waiting, not repeated restarts. Simulated boundary, reset, weekly bottleneck, fallback sequence, cancellation, cooldown and restart recovery checks passed; no real-account exhaustion test was performed.
The account panel now opens the installed Codex app-server's official browser sign-in flow. Complete authentication in your system browser to import an encrypted account without logging out of or switching the active Codex account. Cancel, reopen and a five-minute timeout are supported. Existing accounts are updated; the active identity retains its live credential.
The helper uses an isolated temporary CODEX_HOME, without the real configuration, sessions or credentials, and starts no model tasks. The official helper temporarily writes plaintext auth.json there. Imported snapshots use existing DPAPI / Keychain encryption; temporary files are cleaned after completion, cancellation or failure, and leftovers are cleaned on the next launch. Automatic switching pauses while login is pending. Passwords and verification codes stay on the official page.
Isolated import, duplicate identity, encrypted rollback, cancellation, timeout and UI checks passed. Starting and cancelling the installed official login flow preserved the real auth and configuration. Real user authentication and macOS runtime behavior remain untested. Run npm run account-login:validate.
Account switching now stops the desktop and its app-server before saving the final old credential, backing up, replacing auth, and checking the target identity. Remaining independent Codex CLI clients block the change; they are not automatically terminated. Switching without restart requires clients to be closed first. Re-login and active-account deletion follow the same ordering, and backup failures block replacement.
Quota validation, goal recovery and continuation share the manual account-operation queue. Manual login operations immediately invalidate and persist cancellation of pending recovery. Identity is checked again before goal mutation and transport dispatch; the goal helper must exit before the queue is released.
Older, undated or conflicting same-date imports show a rollback warning and require re-login. Import, metadata hydration and unchanged-file synchronization preserve existing re-login markers. Validation uses fake credentials, mocked processes and desktop services, plus a local pipe. No real-account switching or exhaustion test was performed; external clients do not share a global file lock, and platform enforcement is outside these fixes.
The all-accounts quota overview now has an eye toggle beside its heading. It replaces account names with numbered aliases and restores them on the next click. The local display preference survives refresh and restart and applies only to this overview.
The switch reminder is now a 320 × 112 card matching the widget, retaining the 15-second countdown, cancel button and Escape shortcut. Target account and task count are available on hover instead of in a large text block.
After confirming the original task has a new continuation turn, recovery opens it through Codex's navigate_to_codex_page. A batch opens only its first confirmed task once. Navigation failure or an unsupported interface does not interrupt recovery or resend a continuation; the status suggests opening the task manually. The rendered card, countdown/cancel interaction, batch deduplication and failure isolation were checked, and the local task navigation interface was exercised successfully.
Recognizes the complete native You’ve hit your usage limit. Upgrade to Pro (...) template when the desktop returns it in a failed turn without an error code. Recovery is triggered by the failed turn, not by the widget estimate reaching zero; a 99%-used snapshot does not suppress exhaustion detection. Busy-task checks, the cancellable 15-second countdown, post-switch verification and continuation deduplication are retained.
Regression fixtures based on the observed local error verify countdown, switching and continuation with 1% remaining. A 99% snapshot alone, completed/interrupted turns, historical failures, tool text and non-quota errors do not trigger recovery. The full production flow has not been tested by exhausting another real account.
The current-account usage scope is now labeled as the current local period, with its account-switch start time shown above the metrics. All-local usage explicitly includes different accounts. Missing login, an untracked account, or a missing switch boundary yields unknown usage instead of assigning all local history to the current account.
The official profile's lifetime token count comes from server-side stats.lifetime_tokens, with a stats_as_of cutoff. Local event totals are a different metric. The observed official profile cache has no account identifier, so the active login or cache timestamp alone cannot safely assign it to an account. This version retains local-only reads and adds no official network queries.
Current-account statistics skip session files last modified before the account switch. Growing JSONL logs retain parsing checkpoints and process appended data only. Incomplete lines are re-read after completion; truncation, replacement or detected rewrites trigger full parsing. Compressed archives retain full reads. Concurrent refreshes share work, and invalidated in-flight requests cannot refill a newer cache.
Independent sessions with coincident timestamps and token counters are no longer incorrectly deduplicated; copies and inherited fork history remain deduplicated. Project usage follows the directory at each event. Switching between current-account and all-local statistics cannot be overwritten by an older response.
In a local benchmark with approximately 2.8 GB across 240 log files, initial current-account usage loading fell from 12.7 seconds to 0.11 seconds by reading 5 relevant files. Appending to a roughly 12 MB fixture fell from 30 ms to 1 ms. Fixed event samples preserved all token totals, and incremental, concurrent, compressed-log, deduplication and scope regression checks passed. Results vary with local data; the first all-local read still scans historical logs, and totals remain limited by local log coverage.
Recognizes failed turns where Codex reports Your workspace is out of credits. Add credits to continue. without an error code. Only the latest eligible failure after enablement is handled; ordinary network/tool errors, manual interruptions and failures already followed by another turn remain excluded.
Read-only probes rediscover the local endpoint and retry once after a transport failure. Continuation requests are never automatically replayed. A successful scan clears a stale connection error. Validated the observed error shape, simulated switching/recovery, reconnection and duplicate-send guards, plus read-only connectivity to the installed desktop. The full flow has not been retested by exhausting a real account.
The existing automatic recovery toggle now recognizes local goals entering usageLimited after enablement, including interruptions between goal turns. Multiple goals share the existing batch recovery and cancellable countdown. Manually paused, blocked, completed, budget-limited and historical goals are excluded. Other active goals prevent restarting, including idle gaps between turns.
After verifying the new account and quota, Codex's thread/goal/get and thread/goal/set APIs restore only the original goal's status, preserving its objective, budget, token usage and elapsed time. A short-lived metadata helper never loads a thread or starts model work; continuation uses the desktop app. Recovery confirms both a new turn and the original goal's running state. Incompatibility or uncertain results require manual inspection without duplicate sends. Requires a compatible Windows Codex desktop installation.
Validated simulated batch recovery and cancellation/state-change guards, plus the installed Codex goal API in an isolated home with preserved accounting and no model turn. Real quota exhaustion, account switching, restart and sustained goal continuation have not been tested end to end.
Credential file associations now use platform-specific configuration: Windows keeps its dedicated ICO, while macOS uses the generated application icon. This fixes the missing ICNS resource during Mac packaging. Includes the countdown, cancellation, automatic recovery and batch credential migration updates from 0.1.23. Automatic recovery remains Windows only.
The long explanation is now behind a hover/focus information icon. Before every automatic switch, including fallback accounts, an always-on-top reminder beside the floating widget shows the target account and a 15-second countdown. Cancel, close, or Escape skips this batch of interrupted turns without disabling recovery for new failures. Cancellation persists across application restarts.
The countdown starts after the reminder loads. Disabling recovery, a failed reminder, or a sleep/stall that skips the countdown cancels the operation. Accounts and task activity are checked again afterward. Recovery sends a continuation message to the original task; it does not restore an interrupted process. A real quota-exhaustion recovery has not been tested end to end.
Automatic recovery now prefers Plus → Business with a five-hour limit → weekly-only Business without a five-hour limit. The local team plan name is treated as Business; a recorded 300-minute quota window identifies the five-hour variant. Within each group, higher estimated remaining quota comes first, then the earlier upcoming reset. Other plans and ambiguous window metadata come last. Existing availability checks and exhausted-account exclusions still apply.
Enable the new toggle in the account page's switching settings (off by default). Every 15 seconds, CodexAuth checks local tasks for explicit quota exhaustion failures occurring after enablement. It uses the plan priority above, then ranks each group by the lower estimated remaining session/weekly percentage, breaking ties by the earliest upcoming reset. Recorded snapshots older than seven days and unreset windows with 2% or less remaining are excluded. Only Business accounts with missing or unknown quota can serve as the final fallback. Passed reset times may make an account a candidate, but are never treated as verified availability: after switching, Codex verifies the active account and actual quota before continuing. An unavailable candidate is skipped for another account and excluded for 30 minutes.
Recovery waits for other local tasks to finish, switches credentials using the existing backup flow, restarts Codex, verifies the target account and available quota, then sends a visible continuation prompt to the original task without changing its model or permissions. Restart is required regardless of the manual-switch restart preference. A durable local auto-recovery.json journal prevents duplicate sends. Disabling cancels subsequent recovery steps; already started tasks continue. Reset credits are never automatically consumed.
Currently Windows only. Keep CodexAuth running and the Codex task window available. The desktop app-tools interface is version-dependent; incompatibility or recovery errors appear beside the toggle. Read-only desktop integration and simulated recovery have been validated; a real quota-exhaustion account switch has not been tested.
The credential importer now opens a multi-select file picker first (up to 100 files), then asks once for their shared migration password. Retry an incorrect password without selecting the files again. Import files with different passwords separately. The whole batch is validated before writing; existing accounts use one update confirmation, and the current login is preserved.
Notify Explorer after the .codexauth file type and icon have been registered, so an open folder does not keep the old generic file type and blank icon after an upgrade.
The Windows installer now installs a standalone ICO for .codexauth credentials and registers it as the file type icon. Reinstalling refreshes the association and notifies Explorer. Credentials are still imported through the main window.
Click Export account credentials and choose the current account or all accounts. Export all creates a new folder containing one encrypted .codexauth file per saved account, including the current login without duplicates. All files use the chosen migration password, and the current account uses its latest credentials. Each file works with the existing importer.
Discover redirected Codex cache profiles from Windows Store / MSIX installations and continue past damaged responses in cache hash chains. Account-verified reset credits can now be read without a switch timestamp and saved without a new quota event. Concurrent refreshes preserve the newest reset record, including snapshots with no quota windows. All quota reads remain local; missing records remain unknown.
Click the version above the main window title or beside the widget brand to check the latest public GitHub release. A newer release offers the installer matching the current OS and architecture; Download opens it in your browser for manual installation. Failed checks can be retried, and newer local builds are not offered a downgrade.
Checks are manual and send no account, credential or usage data. There are no background checks or automatic installs. Uses the public GitHub Releases API.
After installation, .codexauth encrypted credential files use the CodexAuth app icon. Use Import credentials in the main window to import a file.
Download the latest release · Full v0.1.15 release notes
Use Export current account on computer A with a migration password of at least 10 characters. Install this version or newer on computer B, import the encrypted .codexauth file with the same password, then select Switch for the imported account. Importing does not automatically change the active login or restart Codex.
The file encrypts account labels and credentials using scrypt and AES-256-GCM. Imported credentials are protected again by the destination's DPAPI or macOS Keychain. Updating an existing inactive account requires confirmation and creates a local encrypted backup; an already active account keeps its local credentials. Passwords are not saved or recoverable.
Valid credentials may avoid signing in again, but cannot bypass verification. Expiration, revocation or refresh-token rotation can require a new export or official sign-in. Validate with npm run portable:validate.
- Remove additional quota pools from the widget, account details and usage dashboard. Session quota, weekly quota and reset counts remain available.
- Reduce the widget minimum height while retaining two complete account rows.
- Repeated launches wait for initialization and IPC registration before opening either window, preventing the missing
state:gethandler error. - Initialization failures show an error and exit. Validate with
npm run startup:validate.
- Reserve enough minimum height for two complete account rows, including the additional-pool summary. Previously saved smaller bounds are corrected automatically.
- Compact the reset-count line and label its source as Codex cache.
- The widget account popover and main account details show saved reset counts, source, timestamp and additional quota pools for each account.
- Snapshots remain available after switching accounts. Missing values stay unknown and stale reset counts are labeled; no online refresh is performed for other accounts.
- Read existing Codex browser usage-response caches after matching both account ID and user ID to the active account.
- Label the cache source and timestamp, with stale-data indicators. Missing or unverifiable data remains unknown; no official API requests are made.
- Validate with
npm run browser-cache:validate.
- Quotas are separated by limit ID, with correct weekly-only window placement. Null usage means unknown.
- Token totals use event deltas across sessions and archived sessions, with copied-event deduplication, per-model/day attribution and gzip/Zstandard support where the runtime supports it. Cached input and reasoning output are subsets, not additional tokens. Exact counts and scan coverage are shown. Counter resets or missing baselines are reported rather than guessed.
- Quota estimates learn only from this account's local samples for the same model, explicit speed tier, limit ID and window. Unknown/new models do not inherit GPT-5.5 prices. At least three local samples are required; snapshots remain visible without calibration.
- Earned reset counts are shown only from structured local Codex records. Missing data is Unknown, not zero. Stale or expired records are labeled; there are no online queries or reset-redemption actions.
- Local diagnostics show the running app version, credential sync and log availability. A corrupted account index is recovered from decryptable snapshots after preserving the damaged index and encrypted blobs in a recovery directory.
- Run
npm run local-data:validatefor the fixture-based parser, recovery and integration checks.