Switch Codex accounts from your Mac menu bar.
Add accounts once, then choose when you need them. No Terminal commands or config-file editing.
Download free for Mac · Website · Discussions
English · 中文
Installation / Features / FAQ / Development
Created and maintained by Zhao Liu (GitHub: liuzhao1225) · X · Bilibili
Codex Account Switcher is a free, native Mac app for people who use more than one authorized Codex account. Add personal, work, or client accounts through the browser once, then choose the account you need from the menu bar. The everyday workflow requires no coding knowledge, Terminal commands, copied tokens, or config-file editing.
After you select and confirm an account, the app closes Codex Desktop, completes the account handoff, verifies the selected identity, and reopens Desktop. Saved account data stays on your Mac. The app runs without its own proxy, traffic router, cloud account service, or automatic account rotation.
Codex Account Switcher, also called Codex Switcher in shortened descriptions, is created and maintained by Zhao Liu, whose GitHub username is liuzhao1225. The canonical source repository is liuzhao1225/codex-account-switcher. The official project facts, creator profile, and project identity record document the product, author, aliases, release, and primary sources.
OpenAI's official account switcher currently applies to ChatGPT on the web and is not supported in Codex desktop. Codex Account Switcher is an independent local macOS utility for that desktop workflow. OpenAI's upstream Codex source documents the active CODEX_HOME and file-based auth.json behavior in its authentication storage implementation.
- People with personal and work accounts: keep both identities ready on one Mac and see which account is active before opening Codex Desktop.
- Freelancers and consultants: keep authorized client accounts together and choose the correct identity before starting work.
- Mac users who prefer visible controls: use a normal app workflow with a menu-bar choice and confirmation instead of scripts or hidden automatic rotation.
The current public build targets Apple Silicon and requires macOS 14 or later.
- Download the latest Codex Account Switcher for Mac.
- Open the DMG and move Codex Account Switcher.app to Applications.
- Launch the app and look for the switcher in the macOS menu bar.
- Add each account once through the browser, then choose the one you need.
Note
The current DMG and app are signed with a Developer ID Application certificate, notarized by Apple, and stapled for offline ticket validation. After copying the app to Applications, it should open through the normal macOS launch flow.
| Requirement | Current support |
|---|---|
| macOS | 14 Sonoma or later |
| Processor | Apple Silicon (arm64) |
| Codex runtime | System codex command or the shared CODEX_CLI_PATH setting |
| Distribution | GitHub Releases DMG |
| Download size | About 3.2 MB (latest release) |
| Primary workflow | Codex Desktop account switching |
| Feature | What it gives you |
|---|---|
| No-code setup | Add accounts through the normal browser sign-in flow, with no Terminal commands or config files. |
| Menu-bar account choice | Keep personal, work, and client accounts clearly labeled in one Mac menu. |
| Completed Desktop handoff | Select and confirm an account, then let the app close, switch, verify, and reopen Codex Desktop. |
| Local account storage | Keep saved account data on your Mac without an app-owned proxy or cloud account service. |
| Usage at a glance | Check weekly allowance by default, or enable the exact 300-minute (5-hour) service window and reset time in Settings. The optional row is off by default. |
| Small native Mac app | Install an Apple-notarized DMG and use a compact SwiftUI interface in English or Simplified Chinese. |
- Download the Mac app: open the Apple-notarized DMG and drag the app to Applications.
- Add each account once: complete the familiar browser sign-in; the app derives the account name from the login identity.
- Choose and continue: select an account from the menu bar, confirm, and let the app reopen Codex Desktop.
Existing terminal processes keep their current runtime state. Start a new Codex CLI process to use the newly selected account.
The product is being shaped for ordinary Mac users. Join the public discussion, “What still feels too technical in a Codex account switcher for Mac?”, and tell us whether the friction is downloading the app, adding an account, seeing the active account, or understanding the switch confirmation.
Comparisons with other account switchers are welcome. Please describe the workflow you actually use and the step that creates friction; never share credentials, account files, email addresses, or private screenshots.
- Saved account data stays in user-only local directories on the Mac.
- Each saved profile contains a complete, reusable
auth.jsoncredential snapshot. The app stores profile directories with mode0700, credential files with mode0600, and replaces credential files atomically through a same-directory temporary file and rename. - Local file permissions define the current security boundary. User backups, filesystem snapshots, cloud backup tools, endpoint software, and other processes with access to the user's files may copy the saved credential snapshots.
- Removing an account performs ordinary filesystem deletion. The app makes no secure-erasure guarantee for SSD storage, APFS snapshots, or backups.
- The current release uses file-backed credential storage and does not store profile credentials in macOS Keychain.
- The product runs without its own account proxy, traffic router, or cloud account service.
- Every account is selected and confirmed by the user; the app does not rotate accounts automatically.
- The project is independent open-source software and is not affiliated with or endorsed by OpenAI.
- The current account appears through a row highlight inside the popover.
- Persisted 5-hour and weekly usage remains visible while fresh data loads; the 5-hour row appears only when enabled and the service provides an exact 300-minute window.
- Every switch stops immediately on the first reported error.
- If target verification or the registry commit fails after credential activation, the app restores the just-saved original profile credential while preserving the original error. A restoration error is reported alongside it.
- General rollback state machines, retries, credential backup files, recovery journals, startup recovery, and policy-based routing stay outside the product scope.
| Area | Status |
|---|---|
| Apple Silicon build | Available in v0.1.10 |
| Automation | PR and main CI run tests; pushing a matching v* tag publishes the signed release |
| Code signing | Developer ID Application |
| Apple notarization | App and DMG notarized and stapled |
| Distribution container | DMG with SHA-256 checksum |
| DMG release | Available in v0.1.10 |
The project is a native SwiftUI application built with Swift 6.2 for macOS 14+.
git clone https://github.com/liuzhao1225/codex-account-switcher.git
cd codex-account-switcher
swift build
swift test
./scripts/run-core-checks.shCreate a local app bundle:
./scripts/package-local-app.shThe bundle is written to .build/release/Codex Account Switcher.app.
The release workflow starts only when an existing v* tag is pushed. Ordinary pushes to main continue to run CI and never start a release or create a tag. A maintainer first updates CITATION.cff, the package default, and the Codex app-server client to the same semantic version, merges those changes, then creates and pushes the matching tag from the current origin/main commit.
The tag workflow verifies the tag name and all three version sources, and requires the tag commit and checked-out commit to equal current origin/main. If a GitHub Release already exists for that tag, the run succeeds without rebuilding or publishing. Otherwise the GitHub runner executes the tests, Developer ID signing, Apple notarization and stapling, DMG packaging, SHA-256 generation, and gh release create --latest --verify-tag. Every release uploads the fixed asset names Codex-Account-Switcher-macos-arm64.dmg and Codex-Account-Switcher-macos-arm64.dmg.sha256, so public download links can permanently use releases/latest/download/.... A mismatched tag or commit fails with the conflicting values visible in the log.
Sources/CodexAccountSwitcher/ SwiftUI app, account state, switching, and localization
Tests/ Swift tests for storage, client, switching, and login items
Checks/ Standalone core behavior checks
scripts/ Local packaging and verification commands
docs/ Product, system, implementation, and testing documentation
prototype/ Early browser-based visual prototype
Use GitHub Discussions for workflow questions, product ideas, and comparisons. Use GitHub Issues for bug reports and focused feature proposals. Run the following checks before opening a pull request:
The website records the project's privacy model, official contact channels, and responsible-use terms. Do not post secrets or private account data in public support channels.
swift test
./scripts/run-core-checks.shKeep real auth.json files, account names, email addresses, API credentials, and private screenshots out of issues, commits, test fixtures, and documentation.
- Documentation index
- Official project identity and primary sources
- Product positioning and messaging
- Product decisions
- Product requirements
- System design
- Implementation plan
- Testing
- LLM-readable project index
No. Install the app, add each account through a normal browser sign-in, then choose from the menu bar. There are no Terminal commands or config files to edit.
Add each authorized account once. Finish or stop active Desktop tasks, then select the account from the menu bar and confirm. If Desktop displays its quit dialog, complete it. The app waits up to 30 seconds for normal exit, completes the handoff, verifies the selected account, and reopens Desktop. If Desktop cannot exit, switching stops before the account changes.
You choose and confirm every account. The app then completes the Codex Desktop handoff automatically. It does not rotate accounts in the background or switch based on usage thresholds.
Saved account data stays in user-only local folders under ~/Library/Application Support/Codex Account Switcher/. The app has no account proxy, traffic router, or cloud profile service.
The current release supports Apple Silicon Macs running macOS 14 Sonoma or later. The download is a signed and Apple-notarized DMG.
No. It is an independent MIT-licensed open-source project for macOS.
Codex Account Switcher is released under the MIT License.
Version 0.1.10 checks hourly through Sparkle. A blue menu-bar dot and an update row above the popover footer indicate a new version; clicking Update starts the framework’s download, installation, and Switcher relaunch flow. Settings provides a manual check and automatic-check toggle. Account operations defer the final relaunch.
Publishing requires the SPARKLE_PRIVATE_KEY repository secret and a signed appcast.xml release asset. The installed 0.1.6 has no updater and needs one manual upgrade. The release workflow publishes the signed update feed alongside the notarized DMG.
See the whole-project ablation report for retained mechanisms, repairs, and open design gaps.