CC-Switch Quick Configuration Tool

CC-Switch is an All-in-One AI CLI manager. It provides a desktop UI for managing provider configurations, MCP servers, system prompts, and extension workflows for tools such as Claude Code, Codex, and Gemini CLI.

Best For

Use CC-Switch when you frequently switch between official services, PotatoAI.cc, and other relay configurations. It reduces formatting mistakes from manually editing config files.

• Related Links
• Overview
• Core Features
• Installation
  • Windows
  • macOS
  • Linux
• Quick Start
  • 1. Initialize Settings
  • 2. Add a Claude or Gemini Provider
  • 3. Add a Codex Provider
  • 4. Switch Providers
  • 5. Apply the Configuration
• Full Documentation
• Project Resources
• Start Using It

Related Links

Resource	Link
GitHub Releases	github.com/farion1231/cc-switch/releases
GitHub Repository	github.com/farion1231/cc-switch
CC-Switch Docs	ccswitch.lovable.app
PotatoAI.cc API Key	Create an API Key

Overview

CC-Switch is a cross-platform desktop app for managing Claude Code, Codex, and Gemini CLI from one place. It offers provider switching, API endpoint tests, MCP server management, system prompt management, and Claude Skills management through a visual interface.

Core Features

Feature	Description
Provider switching	Save multiple endpoints and API keys for Claude Code, Codex, and Gemini CLI, then switch with one click.
API endpoint checks	Test endpoint speed and use quality indicators to evaluate availability.
System prompt presets	Manage multiple prompt presets for different development tasks.
MCP server management	Manage MCP server configuration with a unified structure.
Claude Skills management	Discover and install Claude Skills.
Backup and restore	Keep the latest 10 configuration backups automatically.
Deep links	Support ccswitch:// deep-link workflows.
Environment checks	Detect environment variable conflicts that may affect tool calls.

Installation

Windows

Recommended: MSI Installer

1. Open GitHub Releases.
2. Download the latest .msi installer.
3. Run the installer and follow the setup wizard.
4. Launch CC-Switch from the Start menu.

Portable Version

1. Download the .zip portable package.
2. Extract it to any folder.
3. Run cc-switch.exe.

macOS

Homebrew is recommended:

brew tap farion1231/ccswitch
brew install --cask cc-switch

Manual Install

1. Open GitHub Releases.
2. Download the .dmg installer.
3. Open the DMG and drag CC-Switch into the Applications folder.
4. Launch it from Launchpad or Applications.

Linux

Debian / Ubuntu

sudo dpkg -i cc-switch_*.deb
sudo apt-get install -f

AppImage

chmod +x cc-switch_*.AppImage
./cc-switch_*.AppImage

Arch Linux

paru -S cc-switch-bin
# Or use yay
yay -S cc-switch-bin

Quick Start

1. Initialize Settings

Open CC-Switch, go to Settings, then open the General tab and enable the recommended Window Behavior options.

Recommended Options

Enable startup launch, silent launch, Claude Code plugin integration, skip first-install confirmation, and minimize to tray on close for the smoothest desktop experience.

2. Add a Claude or Gemini Provider

Click the plus button in the upper-right corner to add a provider configuration for Claude Code or Gemini CLI.

Gemini Users

If you use Gemini CLI, create a Gemini-specific token on PotatoAI.cc instead of reusing a Claude token group.

3. Add a Codex Provider

Click the plus button again to add a Codex provider configuration.

Field	Suggested Value
Base URL	https://www.potatoai.cc/v1. If the console shows a different dedicated URL, use the console value.
API Key	Use the key created for the matching tool token group.
Model	Copy the full model ID from Model Square or the console.
Tool type	Claude Code, Codex, and Gemini CLI should use separate configurations.

Important

Different AI tools require different token groups. Do not reuse tokens across Claude Code, Codex, and Gemini CLI, or you may see unavailable-model or permission errors.

4. Switch Providers

1. Select the configuration you want in the provider list.
2. Click Enable or Use Current.
3. You can also switch instantly from the system tray icon.

System Tray Switching

Right-click the CC-Switch tray icon, then choose the tool and provider configuration from the menu. Claude Code supports hot reload; other tools usually work best after a restart.

5. Apply the Configuration

After switching, close and restart the corresponding AI tool so it reads the new configuration.

Tool	Recommendation After Switching
Claude Code	Usually supports hot reload; restart if anything looks wrong.
Codex / Codex CLI	Close the app or terminal session, then start it again.
Gemini CLI	Close the terminal session, then start it again.

Full Documentation

For detailed configuration and advanced features, see the CC-Switch docs site.

Project Resources

Item	Link
GitHub Repository	github.com/farion1231/cc-switch
Issues	GitHub Issues
Latest Version	Releases page

Start Using It

You can now use CC-Switch to manage multiple AI coding tool configurations: create separate tokens for each tool, save multiple relay providers, and switch from the main window or system tray.