ai-code-switcher
Switch between profiles for AI coding tools and launch the right CLI with the right environment.
ai-code-switcher gives each profile its own provider, endpoint, credentials,
proxy, and default arguments. The code-ai command then starts Claude Code,
OpenAI Codex, or Grok using that profile.
Features
- Manage multiple profiles from one command-line interface
- Support API-key and isolated login/credential profiles
- Configure a custom endpoint and proxy for each profile
- Forward arguments to the underlying AI CLI
- Set per-profile default arguments such as
--model - Upgrade the supported AI CLIs through npm
- Optional Windows and macOS desktop launcher
Installation
Install the CLI from PyPI:
python -m pip install ai-code-switcher
For local development, install the checkout in editable mode:
python -m pip install -e .
The optional desktop launcher is installed with:
python -m pip install "ai-code-switcher[desktop]"
Requirements:
- Python 3.9 or later
- At least one supported AI CLI installed and available on
PATH - Node.js and npm for
code-ai upgrade - Windows or macOS for the optional desktop launcher
Quick start
Create a profile interactively, then launch it:
code-ai add
code-ai list
code-ai show my-claude
code-ai run my-claude
Arguments after the profile name are forwarded to the underlying CLI:
code-ai run my-claude -p "Review this repository"
code-ai run my-codex --model o3
code-ai run my-grok --help
Useful commands:
code-ai list List configured profiles
code-ai add Add a profile interactively
code-ai show <profile> Show profile details
code-ai remove <profile> Remove a profile
code-ai upgrade Upgrade Claude, Codex, and Grok CLIs
code-ai --version Show the installed version
code-ai --help Show command help
The supported AI CLIs are:
- Claude Code:
@anthropic-ai/claude-code - OpenAI Codex:
@openai/codex - Grok:
@xai-official/grok
code-ai upgrade also refreshes the Grok binary in each login profile's
credentials directory. Grok stores a separate binary under GROK_HOME/bin, so
updating only the global npm package can leave a login profile running an old
version. The upgrade enables npm install scripts and verifies the actual binary
version in the default home and every login home; an unchanged or missing binary
causes the command to fail. Restart running Grok sessions after upgrading.
For Grok, code-ai run prefers the official package in the active npm global
prefix, so an older native installation earlier on PATH cannot shadow the
package updated by code-ai upgrade. Native installations remain supported
when the npm package is absent. Login credentials still use the profile's own
GROK_HOME.
Profiles and configuration
Profiles are stored in ~/.code-ai/config.yaml. Use API mode when the profile
should provide a token or API key. Use login mode when the CLI should use an
isolated credentials directory.
Example configuration:
profiles:
claude-api:
name: claude-api
type: claude
mode: api
base_url: https://api.anthropic.com
token: sk-ant-...
default_args:
- --model
- claude-sonnet-4-5
codex-login:
name: codex-login
type: codex
mode: login
credentials_path: ~/.codex-profiles/work
proxy: http://127.0.0.1:7890
grok-api:
name: grok-api
type: grok
mode: api
base_url: https://api.x.ai
api_key: xai-...
Login profiles isolate credentials through the provider-specific environment variables used by the CLIs. API profiles set the corresponding endpoint and authentication variables for the selected provider.
Keep tokens and personal configuration out of source control.
Default launch arguments
default_args can be a YAML list or a single string:
profiles:
claude-api:
name: claude-api
type: claude
default_args: "--model claude-sonnet-4-5"
Profile defaults are appended after command-line arguments. This lets a
profile pin a value such as --model when the CLI uses the last occurrence of
a flag. Skip profile defaults for one launch with:
code-ai run --no-default-args claude-api --model claude-opus-4-5
Claude Buddy
Claude profiles can have a deterministic companion card generated from the profile name:
code-ai roll-claude-buddy claude-api
code-ai roll-claude-buddy claude-api --name capybara
code-ai roll-claude-buddy claude-api --type legendary
Desktop launcher
The optional desktop launcher provides a graphical interface for detected Claude and Codex desktop apps. It is supported on Windows and macOS.
python -m pip install "ai-code-switcher[desktop]"
code-ai desktop install # create or recreate the shortcut
code-ai desktop run # open the launcher
code-ai desktop uninstall # remove the shortcut
Desktop settings are stored separately in ~/.code-ai/desktop.yaml. The
launcher can check the system proxy and apply common or per-application
environment variables; per-application values take precedence.
Development
Run the test suite and build the distribution locally with:
python -m pytest tests/ -q
python -m build
License
MIT
Metadata
Release files for ai-code-switcher 0.1.23
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_code_switcher-0.1.23.tar.gz | 381.8 kB | Without provenance | Details for ai_code_switcher-0.1.23.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_code_switcher-0.1.23-py3-none-any.whl | Python 3 | none | any | Details for ai_code_switcher-0.1.23-py3-none-any.whl |
Total release size: 749.5 kB
Release files / ai_code_switcher-0.1.23.tar.gz
| Download URL | ai_code_switcher-0.1.23.tar.gz |
|---|---|
| Size | 381.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d129f05be72a097ff00b5c305ad0d0365a62c41d31228aa887433fa633171281
|
|
BLAKE2b-256 checksum How to use checksums |
d533f707d88eb680672e322a9f2ed3ff7b939508ed636b766de832ebea2c7c26
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / ai_code_switcher-0.1.23-py3-none-any.whl
| Download URL | ai_code_switcher-0.1.23-py3-none-any.whl |
|---|---|
| Size | 367.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9c662b4d2ff0b5c327d1b23ae321e5bdec8ba8b2088184e36d41ac6711c2bd0f
|
|
BLAKE2b-256 checksum How to use checksums |
56e8343e0767c99220a9d0569e60ae10d1207d6b7bd092775f943186e395cdc8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for ai-code-switcher 0.1.23
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.