Skip to main content

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)

Source distribution for ai-code-switcher 0.1.23
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)

Table of built distributions (wheels) for ai-code-switcher 0.1.23
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page