# 1.2 Installation Guide

## Official Channels and System Requirements

Only download CC Switch from **[ccswitch.io](https://ccswitch.io)**, **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**, or the project source repository. Any "CC Switch" site or client that asks for payment, top-ups, or login credentials is not official.

| System | Minimum Version | Architecture |
|--------|-----------------|--------------|
| Windows | Windows 10 or later | x64 |
| macOS | macOS 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
| Linux | See distribution notes below | x64 / ARM64 |

## 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](https://nodejs.org/)

2. Download the LTS version installer

3. Run the installer and follow the prompts

4. Verify installation:

 ```bash
 node --version
 npm --version
 ```

#### macOS

```bash
# 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

```bash
# 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)**

```bash
brew install claude-code
```

**Option 2: npm**

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

#### Codex

**Option 1: Homebrew (recommended for macOS)**

```bash
brew install codex
```

**Option 2: npm**

```bash
npm install -g @openai/codex
```

#### Gemini CLI

**Option 1: Homebrew (recommended for macOS)**

```bash
brew install gemini-cli
```

**Option 2: npm**

```bash
npm install -g @google/gemini-cli
```

---

## Windows

### Installer

1. Visit the [Releases page](https://github.com/farion1231/cc-switch/releases)
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)

```bash
# Add tap
brew tap farion1231/ccswitch

# Install
brew install --cask cc-switch
```

Update to the latest version:

```bash
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:

```bash
# 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:

```bash
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:

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

3. Run:

```bash
./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

```bash
# Debian/Ubuntu
sudo apt remove cc-switch

# ArchLinux
paru -R cc-switch-bin
```