cc-switch/docs/user-manual/en/1-getting-started/1.2-installation.md

1.2 Installation Guide

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.zip
2. Extract 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.deb
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.AppImage
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. You can switch between Claude / Codex / Gemini apps

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