Codex Switch is a VS Code sidebar extension that remembers a separate Codex provider for each workspace, from your ChatGPT subscription to nine API-key providers. Keep account usage, searchable models and supported balances with optional alerts in one panel. Keys use your operating system secure storage; switching preserves ChatGPT sign-in, reloads only that window and opens a new Codex chat.
| Provider | Access |
|---|---|
| ChatGPT | Existing ChatGPT subscription and sign-in |
| DeepSeek | API key |
| OpenRouter | API key |
| OpenAI API | API key, separate billing |
| Z.AI (GLM) | Coding Plan API key |
| Moonshot AI (Kimi) | Regional API key |
| Alibaba Cloud (Qwen) | Token Plan or workspace PAYG key |
| xAI (Grok) | API key |
| MiniMax | M Plan or PAYG API key |
| Xiaomi MiMo | PAYG or Token Plan API key |
See provider setup, official sources and compatibility limits. Catalog validation is separate from inference. Test selected model (uses API credits) checks a synthetic function-tool round-trip; it does not certify a full Codex session.
- Open GitHub Releases and choose the newest version with a VSIX attached.
- Download
codex-switch-<version>.vsix. - In VS Code, open Extensions, choose Install from VSIX..., and select the downloaded file.
- Reload VS Code, open Codex Switch from the Activity Bar, configure an API key if needed, and switch providers.
Each workspace keeps its own provider and model preferences when reopened. Current Configuration is confirmed by that window's Codex process and applies to new chats. Existing conversations retain their original provider. An unconfirmed or unapplied selection offers Reload this window, without marking the saved preference as active.
Codex Switch supports VS Code desktop on Windows, macOS and Linux (x64/ARM64),
with Python 3.11+ and a compatible Codex installation. A compatible interpreter
is discovered automatically. Set codexSwitch.pythonPath to select another
interpreter, including a virtual environment.
API keys use VS Code SecretStorage, encrypted on the client and shared between local and SSH windows. Opening a local workspace automatically migrates existing DPAPI/Keychain/Secret Service keys, preserving local encrypted copies for the standalone helper. A connected remote Codex receives keys in memory; the server needs no desktop keyring and stores no API keys. No Python packages, pip commands or virtual environment are needed. Secure-storage failures are reported explicitly.
Runtime state stays in ~/.codex/provider-switcher, or under CODEX_HOME when
set, outside the repository. For SSH, WSL and containers, install Codex Switch
alongside Codex on the remote host. It uses that host's account, Python and secure
vault for standalone use. ChatGPT sign-in remains on its owning host. Shared API
keys stay encrypted on the client and are available remotely while VS Code is connected.
The table describes the changes introduced by each version. Release links open the matching GitHub Release, including its installable VSIX and checksum.
| Version | Changes |
|---|---|
| 0.6.0 | Show the verified workspace provider's remaining usage in the status bar, share live metrics with its card, and add Z.AI quota and MiMo balance/Token Plan readings. |
| 0.5.5 | Confirm restored Codex clients after cold startup, preserve saved providers when Codex activates first, and retain folderless-window selections. |
| 0.5.4 | Confirm the correct Codex account and provider in SSH workspaces, share encrypted API keys without storing them on headless servers, discover compatible Python and preserve ordinary Codex startup. |
| 0.5.3 | Prevent repeated window reloads when opening a workspace, apply its provider when Codex starts before the selector, and blend the supplied pixel art into the banner. |
| 0.5.2 | Fit short model lists to their options, unify multi-provider card widths and labels, and add percentage colors and time markers to ChatGPT usage bars. |
| 0.5.1 | Keep Codex usable when Codex Switch is disabled or removed, restore owned settings conditionally and retain workspace choices and credentials. |
| 0.5.0 | Remember provider and model choices per workspace, isolate simultaneous Codex windows, confirm the applied configuration and open a new chat after switching. |
| 0.4.3 | Remove parenthesized model IDs from OpenRouter model labels while retaining the free-model marker, and add a native Remove API key action with a trash button to the existing-key dialog. |
| 0.4.2 | Keep periodic provider refreshes visually quiet, retain the displayed data until all requests finish, and spin the sync wheel throughout. Initial loading remains unchanged. |
| 0.4.1 | Make secure credential storage ready to use without Python package setup, refine the banner and provider controls, and simplify the provider table. |
| 0.4.0 | Add eight API-key providers through a shared engine, searchable model selection, full-width OpenRouter with laboratory/free-model filtering, explicit model tests, and supported balance/quota information with opt-in alerts. |
| 0.3.3 | Arrange providers in two columns from a panel width of 550px with equal card heights and aligned bottom buttons, retaining natural heights on narrower panels and full width for a single visible provider. |
| 0.3.2 | Add rounded app-style ChatGPT and DeepSeek logos beside each provider name and subtitle. |
| 0.3.1 | Support Windows, macOS and Linux with native credential stores, portable Python paths, configurable interpreter, CODEX_HOME support and cross-platform CI. |
| 0.3.0 | Show the signed-in ChatGPT plan and configuration status, remaining five-hour and weekly usage with exact reset times and countdowns, and available banked resets. Refresh visible providers from one sync control next to the current configuration, without loading hidden providers. |
| 0.2.1 | Hide DeepSeek's model catalog and balance until its API key is validated, show Loading while credential status is pending, keep the provider switch button visible, reveal the API-only sections automatically after successful validation, and allow immediate retries after an invalid key without leaving controls blocked. |
| 0.2.0 | Collapse API-key model catalogs by default, add DeepSeek USD balance with one-minute polling and configurable low or zero balance alerts, and recover ChatGPT settings after CC Switch leaves a custom provider. |
| 0.1.3 | Simplify the English sidebar, add persistent provider visibility and ordering, restore native API key entry and configuration status, improve active and action feedback states, and reload automatically after a successful provider switch. |
| 0.1.2 | Add the supplied logo, README banner and sidebar icon; publish VSIX release assets and link release history automatically. |
| 0.1.1 | Move source into this repository, bundle the local connector with the extension, and document project conventions. |
| 0.1.0 | Initial sidebar selector for ChatGPT and DeepSeek, model and reasoning selection, encrypted API key storage, and connection checks. |
Developer setup
Use Node.js 24, npm, Python 3.11+, and VS Code 1.100 or newer. No additional Python packages are required. Tests exercise the native credential store with isolated temporary identities and disable installed site-packages.
-
Clone the repository and install the locked dependencies:
git clone https://github.com/macorisd/codex-switch.git cd codex-switch npm ci
-
Run the extension, backend, webview, and release tests:
npm test
-
Regenerate the banner and Activity Bar icon when the logo changes, then build the installable package:
npm run brand npm run package
The status-bar font is already bundled. To regenerate it after editing its SVG sources, install the development-only dependency with
python -m pip install -r scripts/requirements-icons.txt, then runpython scripts/build-status-icons.py. Installed extensions need neither fontTools nor this generation step. -
Install the resulting VSIX in the VS Code profile you are testing:
code --install-extension codex-provider-switch-<version>.vsix --force
Runtime state remains in ~/.codex/provider-switcher (or under CODEX_HOME). Preserve
auth.json, config.toml, the encrypted key, and local configuration backups
when testing provider switches. Never commit credentials or runtime state.
See project decisions for the product and delivery rules used by this repository.