Claude China

Switch between profiles for AI coding tools and launch the right CLI with the right environment.

claude-china gives each profile its own provider, endpoint, credentials, proxy, and default arguments. The claudec command then starts Claude Code, OpenAI Codex, or Grok using that profile.

Repository: invoker-bot/Claude-China · PyPI: claude-china · CLI: claudec

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
• Standalone Windows, macOS and Linux desktop launcher

Installation

Install the CLI from PyPI:

python -m pip install claude-china

For local development, install the checkout in editable mode:

python -m pip install -e .

Download the desktop app from GitHub Releases. It includes Python and the desktop dependencies; installing the CLI is optional.

Platform	Download	Install	Uninstall
Windows x64	*-windows-x64-setup.exe	Run the installer	Settings → Apps → Installed apps → Claude China
macOS Apple Silicon	*-macos-arm64.dmg	Drag Claude China to Applications	Quit the app, then move it to Trash
macOS Intel	*-macos-x64.dmg	Drag Claude China to Applications	Quit the app, then move it to Trash
Debian / Ubuntu x64	*-linux-x64.deb	Open with the software installer, or sudo apt install ./<file>.deb	Software manager, or sudo apt remove claude-china-desktop
Fedora x64	*-linux-x64.rpm	Open with the software installer, or sudo dnf install ./<file>.rpm	Software manager, or sudo dnf remove claude-china-desktop

Install a newer package over the existing installation to upgrade. Uninstalling preserves profiles, credentials and settings in ~/.code-ai/.

CLI requirements:

• Python 3.9 or later
• At least one supported AI CLI installed and available on PATH
• Node.js and npm for claudec upgrade

Desktop requirements: Windows 10/11, macOS 12 or later, or a Linux desktop with GTK 3 and WebKitGTK 4.1 (Ubuntu 22.04 or later; Fedora 40 or later). Windows setup installs Microsoft's WebView2 Runtime if it is missing, which requires internet access. Linux package managers resolve system GUI dependencies. The launcher does not install Claude or Codex themselves. On Linux, select an installed desktop application's executable in its settings; terminal commands on PATH are not treated as desktop apps.

Unsigned builds may show an operating-system publisher warning. macOS release builds require maintainer signing and notarization credentials to avoid Gatekeeper warnings; see desktop build instructions.

Upgrading from code-ai / AI Launcher

The 0.2 series renames the distribution from ai-code-switcher to claude-china, the command from code-ai to claudec, and the desktop app to Claude China. The Python module is now claude_china (python -m claude_china.cli).

For desktop use, quit the old launcher from its tray menu, remove the old Python-based AI Launcher / Claude China desktop shortcut, and install the native package from GitHub Releases. On macOS the old shortcut is an AppleScript .app on the Desktop; the new app belongs in Applications.

For CLI use, run:

python -m pip install --upgrade claude-china

Existing profiles, login directories, desktop settings and the single-instance lock continue to use ~/.code-ai/; no credentials need to be copied. You can then remove the old distribution with python -m pip uninstall ai-code-switcher.

For existing scripts that still use code-ai, upgrade the compatibility package:

python -m pip install --upgrade ai-code-switcher

Starting with ai-code-switcher 0.1.24, the old package automatically installs claude-china. Both code-ai and python -m code_ai.cli forward to the new CLI and print a deprecation warning to stderr. Arguments, stdout and exit codes are preserved. Switch scripts to claudec when convenient; removing the old package afterwards leaves the new CLI installed. Internal Python imports should use claude_china. Versions pinned below 0.1.24 retain the old implementation. See the compatibility package for details.

Quick start

Create a profile interactively, then launch it:

claudec add
claudec list
claudec show my-claude
claudec run my-claude

Arguments after the profile name are forwarded to the underlying CLI:

claudec run my-claude -p "Review this repository"
claudec run my-codex --model o3
claudec run my-grok --help

Useful commands:

claudec list                         List configured profiles
claudec add                          Add a profile interactively
claudec show <profile>               Show profile details
claudec remove <profile>             Remove a profile
claudec upgrade                      Upgrade Claude, Codex, and Grok CLIs
claudec --version                    Show the installed version
claudec --help                       Show command help

The supported AI CLIs are:

• Claude Code: @anthropic-ai/claude-code
• OpenAI Codex: @openai/codex
• Grok: @xai-official/grok

claudec 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, claudec 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 claudec 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:

claudec 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:

claudec roll-claude-buddy claude-api
claudec roll-claude-buddy claude-api --name capybara
claudec roll-claude-buddy claude-api --type legendary

Desktop launcher

The standalone desktop launcher provides a graphical interface for Claude and Codex desktop apps. Install it from GitHub Releases and open Claude China from the Start Menu, Applications, or your Linux application menu.

claudec desktop download     # optional: print the Release download URL

claudec desktop install and uninstall are retired and display migration instructions. The operating system owns installation, shortcuts and removal.

Only one launcher runs per user. Opening the app again restores and brings the existing window forward. On Windows and macOS, closing the window hides it in the system tray (the menu bar on macOS). Click the tray icon or choose 打开 Claude China to reopen the window; choose 退出 from the tray menu to exit the launcher completely. On Linux, closing the window exits the launcher, including on desktops without a notification tray.

The launcher uses the terracotta Claude China mark for its window, shortcut, tray and footer. The tray/menu-bar and footer marks briefly breathe and turn when the launcher opens or an action runs, then return to rest. Shortcut and window-title icons stay static. See the icon preview and asset notes.

On Windows, the launcher and its shortcuts share a taskbar identity. Icon files use a content-based filename so new artwork gets a fresh Shell cache entry. The Windows installer updates the Start Menu shortcut and optional desktop shortcut. Restart the launcher after upgrading to refresh the taskbar icon.

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

To run the desktop UI from source:

python -m pip install -e ".[desktop]"
claudec desktop run

Linux source development also needs PyGObject, GTK 3 and WebKitGTK 4.1. Native installer builds and release validation are documented in packaging/desktop/README.md. Pushing a v* tag builds the desktop packages for GitHub Releases and independently publishes the CLI distribution to PyPI.

License

MIT