1.2 Installation Guide

Official Channels and System Requirements

Only download CC Switch from ccswitch.io, GitHub Releases, or the project source repository. Any "CC Switch" site or client that asks for payment, top-ups, or login credentials is not official.

Prerequisites

Install Node.js

The CLI tools managed by CC Switch (Claude Code, Codex, Gemini CLI) require a Node.js environment.

Recommended version: Node.js 18 LTS or higher

Windows

1. Visit the Node.js official website

2. Download the LTS version installer

3. Run the installer and follow the prompts

4. Verify installation:

node --version
npm --version

macOS

# Install with Homebrew
brew install node

# Or use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

Linux

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or use nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

Install CLI Tools

Claude Code

Option 1: Homebrew (recommended for macOS)

brew install claude-code

Option 2: npm

npm install -g @anthropic-ai/claude-code

Codex

Option 1: Homebrew (recommended for macOS)

brew install codex

Option 2: npm

npm install -g @openai/codex

Gemini CLI

Option 1: Homebrew (recommended for macOS)

brew install gemini-cli

Option 2: npm

npm install -g @google/gemini-cli

Windows

Installer

1. Visit the Releases page
2. Download CC-Switch-v{version}-Windows.msi
3. Double-click to run the installer
4. Follow the prompts to complete installation

Portable Version (No Installation Required)

1. Download CC-Switch-v{version}-Windows-Portable.zip
2. Extract to any directory
3. Run CC-Switch.exe

macOS

Option 1: Homebrew (Recommended)

# Add tap
brew tap farion1231/ccswitch

# Install
brew install --cask cc-switch

Update to the latest version:

brew upgrade --cask cc-switch

Option 2: Manual Download

1. Download CC-Switch-v{version}-macOS.dmg (recommended) or CC-Switch-v{version}-macOS.zip
2. Open the DMG, or extract the zip to get CC Switch.app
3. Drag it to the Applications folder

Signed and Notarized

CC Switch for macOS is signed and notarized by Apple. You can install and open it directly — no extra steps needed.

Linux

ArchLinux

Install using an AUR helper:

# Using paru
paru -S cc-switch-bin

# Or using yay
yay -S cc-switch-bin

Debian / Ubuntu

1. Download CC-Switch-v{version}-Linux-x86_64.deb or CC-Switch-v{version}-Linux-arm64.deb for your architecture
2. Install:

sudo dpkg -i CC-Switch-v{version}-Linux-*.deb

# If there are dependency issues
sudo apt-get install -f

AppImage (Universal)

1. Download CC-Switch-v{version}-Linux-x86_64.AppImage or CC-Switch-v{version}-Linux-arm64.AppImage for your architecture
2. Add execute permission:

chmod +x CC-Switch-v{version}-Linux-*.AppImage

3. Run:

./CC-Switch-v{version}-Linux-*.AppImage

Verify Installation

After installation, launch CC Switch:

1. The app window displays correctly
2. A CC Switch icon appears in the system tray
3. The app switcher shows enabled managed apps, and you can switch to the target app panel

Auto Update

CC Switch includes built-in auto-update functionality:

• Automatically checks for updates on startup
• Displays an update prompt in the UI when a new version is available
• Click to download and install

You can also manually check for updates in "Settings > About".

Uninstall

Windows

• Uninstall via "Settings > Apps"
• Or run the uninstaller in the installation directory

macOS

• Move CC Switch.app to Trash
• Optional: Delete the configuration directory ~/.cc-switch/

Linux

# Debian/Ubuntu
sudo apt remove cc-switch

# ArchLinux
paru -R cc-switch-bin