Zion Switcher

Switch between multiple Codex accounts from VS Code, see each account's weekly quota, and get a reminder before the active account reaches its limit.

Zion Switcher is Codex-only. It does not configure custom gateways or manage accounts for other coding agents.

Requirements

• VS Code 1.96 or newer
• The Codex CLI installed and available as codex in your integrated terminal
• A desktop VS Code environment with access to ~/.codex
• Network access to OpenAI for login, quota, and inactive-token refresh

Install

Install from the VS Code Marketplace (Extensions: Install Extensions → search Zion Switcher), or download zion-switcher-0.6.5.vsix from the latest GitHub release and run Extensions: Install from VSIX....

Quick start

1. Sign in to Codex normally with codex login. Zion shows that login as Current Account.
2. Open the Zion icon in the Activity Bar.
3. Select Add account.... Zion opens an integrated terminal with an isolated CODEX_HOME.
4. Finish codex login in that terminal.
5. Select any account row, use Zion: Switch Codex Account, or click the status bar item to switch.
6. Choose Restart now so the Codex IDE extension re-reads the selected credentials. This restarts only the Extension Host, not the full window.

Interface

• Zion sidebar > Codex Accounts shows the current login, saved accounts, email, plan, weekly quota, and reset time. Account rows support switch, rename, login, and delete actions.
• Status bar shows the active account and weekly percentage used. Click it to open the account picker.
• Command Palette exposes account switching, quota refresh, config-file access, and cleanup commands.

Both account surfaces are backed by the same state and update together.

Account model

~/.codex/auth.json is always the live credential file used by the Codex CLI and Codex IDE extension. Zion keeps a private copy of each login in VS Code's extension global storage:

<globalStorage>/
├── accounts/codex/
│   ├── __default__/auth.json
│   └── <saved-account-id>/auth.json
└── active/codex.profile

• Current Account is the machine login first found in ~/.codex/auth.json. It is not a normal saved-account row.
• Saved accounts are created by running codex login with an isolated CODEX_HOME.
• An isolated login may briefly generate Codex runtime data beside its credential. Once auth.json exists, Zion compacts that profile to the credential and refresh lock only. It never copies or links ~/.codex sessions, plugins, logs, or caches into account storage.
• Before switching, Zion snapshots the matching live credentials, atomically writes the target account into ~/.codex/auth.json, and updates its active pointer.
• A direct codex login outside Zion is detected and adopted without replacing a different stored identity.

Zion also installs a small managed zionsw block in ~/.zshrc and, when it already exists, ~/.bashrc. The block clears legacy CODEX_HOME overrides so new terminals use the live ~/.codex login.

For implementation details, see Architecture.

Quota and reminders

Zion reads the weekly usage window for every signed-in account and refreshes it on startup, on a timer, and when Refresh Codex Quota is run.

When the active account reaches the configured threshold, Zion suggests the eligible account with the lowest weekly usage. Switching is always confirmed; declining suppresses the reminder for that active account for the rest of the session or until its usage falls below the threshold.

Zion renews an expired token for an inactive account before reading quota or switching. Duplicate profiles for the same login are refreshed as one identity to avoid racing rotating refresh tokens. Zion never rotates the live account's token chain; Codex remains responsible for it.

Settings

Open Settings and search for Zion.

Commands

Credentials and privacy

• Saved auth.json files contain sensitive OAuth credentials. Zion writes them with owner-only permissions where the operating system supports it.
• Credentials remain local. Zion sends the bearer token only to OpenAI's quota endpoint and sends inactive refresh tokens only to OpenAI's OAuth endpoint.
• Zion does not collect analytics or telemetry.
• Quota results and account metadata are stored in VS Code global state.
• Deleting a saved account removes its profile directory. Reset everything removes every saved account and its cached metadata; it does not uninstall the extension or delete shared Codex sessions/configuration.

See Security for the threat model and vulnerability reporting.

Troubleshooting

The Codex extension still shows the previous account

Choose Restart now after switching. If the automatic restart fails, run Developer: Restart Extension Host from the Command Palette.

An account says Not signed in

Use the row's Log in action and finish codex login in the terminal Zion opens. Do not copy another account's auth.json into the profile.

Zion cannot renew an inactive login

The refresh token may have expired or been revoked. Log in to that saved account again. Zion blocks the switch instead of placing known-expired credentials into the live Codex session.

Quota is unavailable

Run Zion: Refresh Codex Quota. A 401 triggers one guarded token-refresh retry for inactive accounts; other HTTP errors are reported without repeatedly rotating credentials.

Extension details reports a large cache

Version 0.6.5 removes legacy account-profile symlinks and Codex runtime files while preserving credentials. Restart the Extension Host once after updating so Zion can compact existing profiles. Your real ~/.codex/sessions history is outside Zion storage and is not deleted.

Remove Zion's shell hook

Uninstalling the extension does not edit shell startup files. Remove the block between # >>> zion-switcher >>> and # <<< zion-switcher <<< from ~/.zshrc and, if present, ~/.bashrc.

Develop

npm install
npm test
npm run typecheck
npm run build
npm run watch
npm run package

npm run build creates dist/extension.js; npm run package creates zion-switcher-0.6.5.vsix. Press F5 in VS Code to launch an Extension Development Host.

Before opening a pull request, read Contributing. Release history is in the Changelog.

License

MIT