Codex Switcher: a Tauri desktop app for juggling multiple OpenAI Codex CLI accounts

What problem Codex Switcher solves, and for whom

The Codex CLI keeps exactly one active login in ~/.codex/auth.json. If you have a personal account and a work account, or several accounts you rotate to stay inside weekly limits, switching means signing out and signing back in, or hand-editing that file. Codex Switcher is a desktop application that stores multiple accounts and writes the one you pick into that path. The README describes it as "A Desktop Application for Managing Multiple OpenAI Codex Accounts" and lists add, rename, mask, import and export as the account operations.

It is aimed at people who already use the Codex CLI and have accumulated more than one login. The feature list is built around that workflow rather than around casual chat use: quick switching from the main window, the native tray menu or a tray popup, per-account rate-limit cards, usage statistics for OAuth accounts, and scheduled warm-ups. The repository topics (agent, codex, openai, tauri, vibe-coding) point at the same audience. If you have one account and no quota pressure, the app has little to do for you.

How the switcher writes accounts into ~/.codex/auth.json

The core mechanism is file replacement. Before Codex Switcher writes another account into ~/.codex/auth.json, it saves the latest tokens from the account that is currently active, so that switching back restores the current session rather than an older snapshot. That detail exists because ChatGPT can replace an OAuth refresh token after using it, and the older token may then be rejected. Without the save-before-write step, a stored snapshot goes stale the moment the live session refreshes.

Two further safeguards are described. Token refreshes and account switches are serialized, so a background refresh cannot finish late and overwrite the account you just selected. And the app avoids refreshing the active account while Codex or ChatGPT is running; the README tells you to close the running app before switching. There is also a blocked switch recovery flow that detects running Codex sessions and offers to force-close them before retrying.

The app itself is a Tauri shell: a React and TypeScript frontend in src/, a Rust backend in src-tauri/, with Vite as the bundler. Login is dual mode, either ChatGPT OAuth or importing an existing auth.json. A separate binary, codex-web, serves the same UI and backend actions over HTTP through /api/invoke/* routes, which the README says makes it usable over LAN, Tailscale or a remote tunnel if you expose the port safely.

Installing Codex Switcher and adding a first account

The README points at the GitHub releases page as the easiest route, with per-platform files: .dmg for macOS (aarch64 and x64), .exe or .msi for Windows, and .deb, .AppImage or .rpm for Linux. Current macOS builds are not Apple-notarized, and the README gives the quarantine fix for the "app is damaged" message:

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

Building from source needs Node.js v18 or newer, pnpm and Rust. The README gives this sequence:

# 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

The bundle lands in src-tauri/target/release/bundle/. On Windows the pnpm tauri script runs through a POSIX shell wrapper (sh ./scripts/tauri.sh) and will not work in PowerShell or CMD; use pnpm tauri:win dev and pnpm tauri:win build instead.

If you would rather run the dashboard in a browser, pnpm lan builds the frontend and starts the web server on 0.0.0.0:3210. Two environment variables override that: CODEX_SWITCHER_WEB_HOST for the bind host and CODEX_SWITCHER_WEB_PORT for the port. Once the app is open, add an account either through ChatGPT OAuth or by importing an existing auth.json, then switch from the main window or the tray. The account card should show the current 5-hour and weekly limit windows and reset timing.

Warm-ups, reset credits and the quota features

A warm-up sends one minimal request to an account so its current usage window has activity before you need it. Manual warm-ups run for a single account or all accounts from the main window or tray menu. Automatic warm-ups, enabled per account or globally, track the 5-hour window when available and warm it after each reset, as long as the weekly limit is not exhausted. The README's description of the automatic path is cut off mid-sentence at "If only the wee", so the fallback behaviour when the 5-hour window is unavailable cannot be confirmed from the documentation.

The usage side is split in two. Rate limits are the live numbers: 5-hour and weekly windows, remaining percentage, reset timing, credit balance and subscription expiry. Usage Stats are historical and only apply to ChatGPT OAuth accounts; the panel shows lifetime tokens, today, last 7 days, last 30 days, streaks, longest task, token activity, reasoning and activity insights, and most-used integrations. The active account opens that panel by default and others stay collapsed.

Manual reset credits appear as a compact badge beside the plan badge, showing the available count and the closest expiry date. Zero-count results are hidden, and the badge turns amber within 10 days of expiry and red within 3 days. The tray popup carries compact active-account stats for today and the last 7 days, kept separate from the normal rate-limit refresh flow.

Where Codex Switcher breaks or is the wrong tool

The sharpest limitation is token invalidation. If an older version of Codex Switcher already saved an invalid refresh token, the README is explicit: sign in to that account again or remove and re-add it once, because an invalidated token cannot be recovered locally. The save-before-write logic reduces the chance of hitting this, but it does not repair accounts that already lost their token. Anyone upgrading from an early release should expect to re-authenticate at least once.

The second constraint is that the app and the CLI compete for the same file and the same session. The README tells you to close Codex or ChatGPT before switching, and the blocked switch recovery flow exists precisely because running sessions get in the way. If your workflow depends on keeping a Codex session open while you rotate accounts, this design will fight you.

Platform coverage is desktop only. The release list has macOS, Windows and Linux artifacts; there is no iOS or Android build, and no mobile client is mentioned. The browser dashboard is the closest thing to remote access, and running it means binding a port on 0.0.0.0:3210 with API routes behind it, which is a deliberate exposure you have to manage yourself. Finally, the repository has no licence file listed among its top-level entries, so the terms under which you may redistribute or modify it are not stated.

How it differs from scripting the switch yourself

The obvious alternative is a shell script that copies a saved auth.json into ~/.codex/auth.json. That approach is transparent and has no runtime, but it is exactly the approach that breaks on token rotation: a script that only writes a stored file has no way to capture the refreshed token from the account you are leaving, and no way to serialize a background refresh against a switch. Codex Switcher's save-before-write and serialization exist to close that gap, and the README's warning about invalidated tokens is the cost of not having it.

A second alternative is the browser dashboard route the project itself offers through pnpm lan and the codex-web binary. Same backend, different shell: you get the switching and stats without installing a desktop bundle, at the price of exposing an HTTP port. That is a reasonable fit for a headless box or a remote host reached over Tailscale, and a poor fit for a laptop where you would rather not run a listener.

Against a plain multi-profile setup in the CLI, the difference is scope. Codex Switcher adds warm-up scheduling, reset-credit expiry badges, tray display modes and usage statistics. None of those are switching primitives; they are quota management around the switch. If you only need the switch, the extra surface is overhead.

Maintenance, releases and licence status

The last push to the main branch was on 2026-09-09, and v0.2.15 was released the same day, following v0.2.14 on 2026-09-08 and v0.2.13 on 2026-09-06. The repository is not archived. The package.json version is 0.2.18, ahead of the most recent tagged release listed, which suggests version bumps happen between releases; the scripts version:bump, version:patch, version:minor and version:major handle that, and release, release:patch, release:minor and release:major handle publishing.

Upgrade cost is low by design. The app checks the latest GitHub release on startup and, when a newer signed update package is available, shows a prompt and can install it from inside the app. That means staying current is a click rather than a reinstall, but it also means the app makes an outbound request to GitHub on every launch. If that matters in your environment, it is worth knowing before you install.

On licensing: no licence is stated for this repository. Without one, the default position is that no rights are granted beyond what the platform allows, so treat redistribution and modification as unresolved until the project states terms. This is a description of what the repository shows, not legal advice; if you plan to ship it internally or fork it, get the licence question answered first.

Editorial conclusion

Adopt Codex Switcher if you run more than one Codex CLI login on macOS, Windows or Linux and want switching, warm-ups and rate-limit visibility in one place. Skip it if you only ever use a single account, or if you need a mobile client: the release list covers macOS, Windows and Linux packages only. Before trusting it with your logins, back up ~/.codex/auth.json, close Codex and ChatGPT before switching, and confirm on first run that the account you switched to is the one the CLI actually reports.

Frequently asked questions

Official sources

1. Issues
2. Lampese/codex-switcher on GitHub
3. README
4. Releases