Codex Switcher

A Desktop Application for Managing Multiple OpenAI Codex Accounts
Easily switch between accounts, monitor usage, schedule warm-ups, and stay in control of your quota

Features

• Multi-Account Management – Add, rename, mask, import, export, and manage multiple Codex accounts in one place
• Quick Switching – Switch between accounts from the main window, native tray menu, or tray popup while preserving rotated ChatGPT sessions
• Usage Stats – View account usage stats for OAuth accounts, including lifetime tokens, daily buckets, streaks, activity insights, and top integrations
• Manual Reset Credits – See available manual reset credits beside each account plan badge, with the closest expiry highlighted as it approaches
• Automatic Warm-Up – Warm up one account or all accounts manually, after each 5-hour reset window, or at specific scheduled times of day
• System Tray Controls – Use the tray popup to switch accounts, inspect quota and active-account stats, refresh usage, open the main window, or quit the app
• Tray Display Modes – Choose between the app icon with session percentage, a text-only hourly/weekly percentage display, or a hidden tray icon
• macOS Dock Control – Keep Codex Switcher in the Dock or run it as a menu bar only app, with a first-close prompt and a tray fallback
• Rate-Limit Monitoring – View real-time 5-hour session and weekly usage, reset timing, credits, and subscription expiry
• Blocked Switch Recovery – Detect running Codex sessions and offer a force-close flow before retrying the account switch
• Dual Login Mode – Authenticate with ChatGPT OAuth or import existing auth.json files

Installation

Download a Release

The easiest way to install Codex Switcher is from the latest GitHub release:

Download the latest release of this fork

Choose the file for your platform:

• macOS Apple Silicon: Codex.Switcher_*_aarch64.dmg
• macOS Intel: Codex.Switcher_*_x64.dmg
• Windows: Codex.Switcher_*_x64-setup.exe or Codex.Switcher_*_x64_en-US.msi
• Linux Debian/Ubuntu: Codex.Switcher_*_amd64.deb
• Linux AppImage: Codex.Switcher_*_amd64.AppImage
• Linux RPM: Codex.Switcher-*-1.x86_64.rpm

macOS: current release builds are not Apple-notarized. If macOS says the app is damaged, move it to /Applications and remove the quarantine flag:

sudo xattr -dr com.apple.quarantine "/Applications/Codex Switcher.app"
open "/Applications/Codex Switcher.app"

Auto Updates

Codex Switcher checks this fork's latest signed GitHub release on startup and then every 6 hours. When a newer package is available, the app shows an Update prompt and can install it inside the app. To check on demand, open Settings → App updates → Check for Updates. A manual check shows either an available update, confirmation that the app is current, or a visible error.

On Windows, use the NSIS setup executable (-setup.exe) when upgrading an existing NSIS installation. If the installer displays "Uninstall before installing", it is replacing the application files, not requesting you delete your saved account store (~/.codex-switcher/accounts.json). Back up the store before changing installations.

Build from Source

Prerequisites

• Node.js (v18+)
• pnpm
• Rust

# Clone the repository
git clone https://github.com/Lampese/codex-switcher.git
cd codex-switcher

# Install dependencies
pnpm install

# Run in development mode
pnpm tauri dev

# Build for production
pnpm tauri build

Windows: the pnpm tauri script runs through a POSIX shell wrapper (sh ./scripts/tauri.sh) and will not work in PowerShell/CMD. Use the tauri:win script instead: pnpm tauri:win dev and pnpm tauri:win build.

The built application will be in src-tauri/target/release/bundle/.

Run the Dashboard in a Browser

You can also serve the built dashboard over HTTP instead of opening the Tauri shell.

# Build the frontend and start the local-only web server on 127.0.0.1:3210
pnpm lan

Optional environment variables:

• CODEX_SWITCHER_WEB_HOST to override the bind host
• CODEX_SWITCHER_WEB_PORT to override the port
• CODEX_SWITCHER_WEB_SECRET is required when CODEX_SWITCHER_WEB_HOST is not a loopback address. Browser requests send it as a Bearer token; when it is not already available in the current browser session, the dashboard prompts once and keeps the entered value only for that session. The server reads the secret from its runtime environment; it is never part of the frontend build.

The browser dashboard serves the same UI and backend actions through /api/invoke/*. The server uses plain HTTP, so remote access must be carried through an encrypted tunnel or TLS-terminating proxy. Never put the secret in a URL or log it. For example:

CODEX_SWITCHER_WEB_HOST=0.0.0.0 \
CODEX_SWITCHER_WEB_SECRET='replace-with-a-random-secret' \
pnpm lan

Only expose that listener behind an encrypted tunnel or TLS; the secret alone does not encrypt the connection.

Usage and Reset Credits

Codex Switcher shows two kinds of account usage information:

• Rate limits – the account card shows the current 5-hour and weekly limit windows, remaining percentage, reset timing, credit balance, and subscription expiry when available.
• Usage Stats – ChatGPT OAuth accounts can expand the Usage Stats panel to view stats such as lifetime tokens, today, last 7 days, last 30 days, streaks, longest task, token activity, reasoning/activity insights, and most-used integrations. The active account opens this panel by default; other accounts keep it collapsed until needed.
• Manual reset credits – OAuth accounts with available reset credits show a compact badge next to the plan badge. It includes the available count and the closest expiry date, hides zero-count results, and turns amber within 10 days or red within 3 days of expiry.

The tray popup also includes compact active-account stats for today and the last 7 days, while keeping the normal rate-limit refresh flow separate.

Safe Account Switching

ChatGPT can replace an OAuth refresh token after using it. Once replaced, the older token may no longer be accepted. Before Codex Switcher writes another account to ~/.codex/auth.json, it now saves the latest tokens from the account that is currently active. Switching back therefore restores the current session instead of an older snapshot.

Token refreshes and account switches are serialized so a background refresh cannot finish late and overwrite the account you just selected. Codex Switcher also avoids refreshing the active account while Codex or ChatGPT is running; close the running app before switching accounts.

If an older Codex Switcher version already saved an invalid refresh token, sign in to that account again or remove and re-add it once. An invalidated token cannot be recovered locally.

Automatic account switching

Enable Auto-switch when the active account runs out of quota in Settings. It is off by default. While the desktop Switcher is running, it checks once a minute and confirms exhaustion at 100% of either reported usage window. Accounts with credits available are still usable. Unknown quota and failed usage requests never trigger switching.

Switcher checks other saved ChatGPT accounts in order, starting after the current account and wrapping around. It verifies available quota before switching, skips API-key accounts, and leaves the current account alone when none is available. It rechecks the active account before acting so a manual switch or quota reset cancels the automatic decision.

For a running supported Codex desktop, enabling this setting permits automatically closing, switching, and reopening without the manual confirmation dialog, even when manual reopening is disabled. Closing is graceful unless Force close was explicitly selected in Settings. Unsaved work may be lost. If Codex is already closed, only the account changes. Running processes that cannot be reopened automatically are left alone.

The main window shows monitoring, no-capacity, success, and failure status, with a Turn off auto-switch button. A five-minute cooldown follows each switch or error; overlapping checks and manual main-window switches are suppressed. Turning off cancels checks before closing starts; an already-started close/switch/reopen sequence finishes. Quota requests time out after 15 seconds. Keep Switcher running; quitting stops monitoring. On macOS 14+, background suspension is disabled for the main window so tray mode can keep monitoring. Hidden-window timing on older macOS and Windows is platform-dependent and has not been runtime-verified.

macOS Dock and Menu Bar Mode

On macOS, Codex Switcher can either stay visible in the Dock or live only in the menu bar. The first time you close the main window, the app asks which behavior you want and lets you choose whether to show that prompt again.

You can change the same setting later from the tray popup or from the native tray menu under Dock Icon. If you choose Menu Bar Only, the app keeps a visible tray item so you can always reopen the main window or switch back to Dock mode.

Warm-Up

A warm-up sends one minimal request to an account so its current usage window has activity before you need it.

• Manual – warm up a single or all accounts, from the main window or tray menu.
• Automatic – when enabled (per account or for all), the app tracks the 5-hour window when available and warms it after each reset, as long as the weekly limit isn't exhausted. If only the weekly window is available, it warms once after the weekly reset and automatically returns to the 5-hour schedule if that window reappears.
• Timed – pick specific times of day (e.g. 08:00, 13:00, 18:00) from the Timed control in the main window. At each time the app warms all accounts (skipping any whose weekly limit is exhausted), so you control when your 5-hour windows start instead of letting them drift.

Timed warm-up checks the schedule every 30 seconds, runs each configured minute only once per day, and skips missed times if the machine was asleep instead of warming accounts late.

On macOS you can keep the machine awake with the built-in caffeinate command, which stops automatically when the app quits:

caffeinate -i -w "$(pgrep -x 'Codex Switcher')"

Disclaimer

This tool is designed exclusively for individuals who personally own multiple OpenAI/ChatGPT accounts. It is intended to help users manage their own accounts more conveniently.

This tool is NOT intended for:

• Sharing accounts between multiple users
• Circumventing OpenAI's terms of service
• Any form of account pooling or credential sharing

By using this software, you agree that you are the rightful owner of all accounts you add to the application. The authors are not responsible for any misuse or violations of OpenAI's terms of service.

Versioning

Use the version bump helper to keep app versions in sync across Tauri, Cargo, and the frontend.

# Exact version
pnpm version:bump 0.2.1

# Semver bumps
pnpm version:patch
pnpm version:minor
pnpm version:major

# Prepare a release commit and tag
# This prompts for a short release note and runs the version bump first.
pnpm release patch

# Prepare and push a release
# The tag stores the release note for the in-app update prompt.
pnpm release patch -- --push

# For non-interactive use, pass the note explicitly.
pnpm release patch -- --push --note "Fixed account switching issues"

The **Build & Release** GitHub Actions workflow now creates a **draft** release.
Publishing is a separate manual approval step; a tag push alone must not make
an incomplete update available via `releases/latest`.

Before publishing a new release:

1. Confirm the CI jobs and all **four release builds** completed successfully:
   macOS Apple Silicon (arm64), macOS Intel (x64), Windows x64, and Linux x64.
   Do **not** treat the PR's Intel macOS compile check as an ARM64 release check.
2. Inspect the draft's platform installers, updater archives and corresponding
   `.sig` files. Confirm `latest.json` includes the expected platform URLs,
   signatures and the new version.
3. Verify the release tag and source versions match, and test installation and
   updater behavior on the platform(s) available to you.
4. Only then publish the GitHub draft. If the ARM64 hosted runner fails to start,
   leave the release as a draft and retry that build after runner capacity recovers.

Never publish an incomplete updater manifest or change the updater signing key
without a compatible migration plan.

If only the Windows release build fails, repair that platform without rebuilding
the already signed macOS and Linux bundles. First ensure the failed release has
a draft on GitHub, then run this workflow from the current `main`:

```bash
gh workflow run repair-windows-release.yml -R Bl0ck154/codex-switcher --ref main -f version=v0.2.22

The repair workflow checks out the existing release tag for its source, checks the versions, and uploads Windows assets to the existing draft. Verify latest.json and all platform signatures again before publishing.

### Re-login after an authentication error

ChatGPT account cards show **Re-login** for a 401 or an invalid, expired, or reused token error. Open it, select **Start re-login**, and open the login link in your browser. Sign in with the original account and choose the same workspace. Switcher updates that saved account and refreshes usage while keeping its name, ID, and preferences. A different account or workspace is rejected.

For the active account, close Codex or switch to another account first. Switcher checks this again before saving so a running Codex process cannot overwrite the renewed credentials. Inactive accounts can be renewed while Codex stays open. Cancel leaves the saved credentials unchanged. API-key accounts do not use this OAuth flow.