v3.10.3

# CC Switch v3.10.3

## Feature Release

> API Format Selector, Pricing Enhancements, Skills ZIP Install & Linux ARM64 Support

## Added

- **API Format Selector**: Generic API format chooser for Claude providers, replacing the OpenRouter-specific toggle. Supports Anthropic Messages (native) and OpenAI Chat Completions format
- **API Format Presets**: Allow preset providers to specify API format (anthropic or openai_chat) for third-party proxy services
- **Pricing Config Enhancement**: Per-provider cost multiplier, pricing model source (request/response), request model logging, and enriched usage UI (#781, thanks @yovinchen)
- **Skills ZIP Install**: Install skills directly from local ZIP files with recursive scanning support
- **Preferred Terminal**: Choose preferred terminal app per platform (macOS: Terminal.app/iTerm2/Alacritty/Kitty/Ghostty; Windows: cmd/PowerShell/Windows Terminal; Linux: GNOME Terminal/Konsole/Xfce4/Alacritty/Kitty/Ghostty)
- **Silent Startup**: Option to prevent window popup on launch (#713, thanks @funnytime75)
- **OpenCode API Key Link**: API key link support for OpenCode provider form
- **OpenCode Environment Check**: Version detection with Go path scanning and one-click install from GitHub Releases
- **OpenCode Directory Sync**: Auto-sync all providers to live config on directory change with additive mode support
- **AICodeMirror Partner Preset**: Added AICodeMirror partner preset for all apps (Claude, Codex, Gemini, OpenCode)
- **NVIDIA NIM Preset**: New provider preset for Claude and OpenCode with nvidia.svg icon
- **n1n.ai Preset**: New provider preset (#667, thanks @n1n-api)
- **Linux ARM64**: CI build support for Linux ARM64 architecture

## Changed

- **API Format Migration**: Migrate api_format from settings_config to ProviderMeta to prevent polluting ~/.claude/settings.json
- **DeepSeek max_tokens**: Remove max_tokens clamp from proxy transform layer
- **Terminal Functions**: Consolidate redundant terminal launch functions
- **Home Dir Utility**: Consolidate get_home_dir into single public function
- **Kimi/Moonshot**: Upgrade provider presets to k2.5 model
- **Update Badge Icon**: Replace update badge dot with ArrowUpCircle icon

## Fixed

- **Codex 404 & Timeout**: Fix 404 errors and connection timeout with custom base_url; improve /v1 prefix handling and system proxy detection (#760, thanks @Darkbluelr)
- **Proxy URL Building**: Fix duplicate /v1/v1 in URL; extend ?beta=true to /v1/chat/completions endpoint
- **OpenRouter Compat Mode**: Improve backward compatibility supporting number and string types
- **Gemini Visibility**: Correct Gemini default visibility to true (#818, thanks @zhu-jl18)
- **Footer Layout**: Correct footer layout in advanced settings tab
- **Claude Code Detection**: Prioritize native install path for detection
- **Tray Menu**: Simplify title labels and optimize menu separators (#796, thanks @fchange)
- **Duplicate Skills**: Prevent duplicate skill installation from different repos (#778, thanks @yovinchen)
- **Windows Tests**: Stabilize test environment (#644, thanks @cxyfer)
- **i18n**: Update apiFormatOpenAIChat label to mention proxy requirement
- **Error Display**: Use extractErrorMessage for complete error display in mutations

---

# CC Switch v3.10.2

## Patch Release

>This maintenance release adds skill sync options and includes important bug fixes.

## Added

- **Skills**: Add skill sync method setting with symlink/copy options
- **Partners**: Add RightCode as official partner

## Fixed

- **Prompts**: Clear prompt file when all prompts are disabled
- **OpenCode**: Preserve extra model fields during serialization
- **Provider Form**: Backfill model fields when editing Claude provider

---

# CC Switch v3.10.1

## Patch Release

> This maintenance release includes important bug fixes for Windows platform, UI improvements, and code quality enhancements.

## Added

- **Provider Icons**: Updated RightCode provider icon with improved visual design

## Changed

- **Proxy Rectifier**: Changed rectifier default state to disabled for better stability
- **Window Settings**: Reordered window settings and updated default values for improved UX
- **UI Layout**: Increased app icon collapse threshold from 3 to 4 icons
- **Code Quality**: Simplified `RectifierConfig` implementation using `#[derive(Default)]`

## Fixed

- **Windows Platform**:
  - Fixed terminal window closing immediately after execution on Windows
  - Corrected OpenCode config path resolution on Windows
- **UI Improvements**:
  - Fixed ProviderIcon color validation to prevent black icons from appearing
  - Unified layout padding across all panels for consistent spacing
  - Fixed panel content alignment with header constraints

---

# CC Switch v3.10.0

> OpenCode Support, Global Proxy, Claude Rectifier & Multi-App Experience Enhancements

**[中文版 →](https://github.com/farion1231/cc-switch/blob/main/docs/release-note-v3.10.0-zh.md) | [日本語版 →](https://github.com/farion1231/cc-switch/blob/main/docs/release-note-v3.10.0-ja.md)**

---

## Overview

CC Switch v3.10.0 introduces OpenCode support, becoming the fourth managed CLI application.
This release also brings global proxy settings, Claude Rectifier (thinking signature fixer), enhanced health checks, per-provider configuration, and many other important features, along with comprehensive improvements to multi-app workflows and terminal experience.

**Release Date**: 2026-01-21

---

## Highlights

- OpenCode Support: Full management of providers, MCP servers, and Skills with auto-import on first launch
- Global Proxy: Configure a unified proxy for all outbound network requests
- Claude Rectifier: Thinking signature fixer for better compatibility with third-party APIs
- Enhanced Health Checks: Configurable prompts and CLI-compatible request format
- Per-Provider Config: Persistent provider-specific configuration support
- App Visibility Control: Freely show/hide apps with synchronized tray menu updates
- Terminal Improvements: Provider-specific terminal buttons, fnm path support, cross-platform safe launch
- WSL Tool Detection: Detect tool versions in WSL environment with security hardening

---

## Main Features

### OpenCode Support (New Fourth App)

- Complete OpenCode provider management: add, edit, switch, delete
- MCP server management: unified architecture with Claude/Codex/Gemini
- Skills support: OpenCode can also use Skills functionality
- Auto-import on first launch: automatically imports existing OpenCode configuration when detected
- Full internationalization: Chinese/English/Japanese support (#695)

### Global Proxy

- Configure a unified proxy for all outbound network requests (#596, thanks @yovinchen)
- Supports HTTP/HTTPS proxy protocols
- Suitable for network environments requiring proxy access to external APIs

### Claude Rectifier (Thinking Signature Fixer)

- Automatically fixes Claude API thinking signatures (#595, thanks @yovinchen)
- Resolves incompatible thinking block formats returned by some third-party API gateways
- Can be enabled/disabled in Advanced Settings

### Enhanced Health Checks

- Configurable custom prompts for streaming health checks (#623, thanks @yovinchen)
- Supports CLI-compatible request format for better simulation of real usage scenarios
- Improves fault detection accuracy

### Per-Provider Config

- Support for saving configuration separately for each provider (#663, thanks @yovinchen)
- Persistent configuration: provider-specific settings retained after restart
- Suitable for scenarios where different providers require different configurations

### App Visibility Control

- Freely show/hide any app (Gemini hidden by default)
- Tray menu automatically syncs visibility settings
- Hidden apps won't appear in the main interface or tray menu

### Takeover Compact Mode

- Automatically uses compact layout when 3 or more visible apps are displayed
- Optimizes space utilization in multi-app scenarios

### Terminal Improvements

- Provider-specific terminal button: one-click to use current provider in terminal (#564, thanks @kkkman22)
- `fnm` path support: automatically recognizes Node.js paths managed by fnm
- Cross-platform safe launch: improved terminal launch logic for Windows/macOS/Linux

### WSL Tool Detection

- Detect tool versions in WSL environment (#627, thanks @yovinchen)
- Added security hardening to prevent command injection risks

### Skills Preset Enhancements

- Added `baoyu-skills` preset repository
- Automatically supplements missing default repositories for out-of-the-box experience

---

## Experience Improvements

- Keyboard shortcuts: Press `ESC` to quickly return/close panels (#670, thanks @xxk8)
- Simplified proxy logs: cleaner and more readable output (#585, thanks @yovinchen)
- Pricing editor UX: unified `FullScreenPanel` style
- Advanced settings layout: Rectifier section moved below Failover for better logical flow
- OpenRouter compatibility mode: disabled by default, UI toggle hidden (reduces clutter)

---

## Bug Fixes

### Proxy & Failover

- Immediately switch to P1 when auto-failover is enabled (instead of waiting for next request)

### Provider Management

- Fixed stale data when reopening provider edit dialog after save (#654, thanks @YangYongAn)
- Fixed baseUrl and apiKey state not resetting when switching presets
- Fixed endpoint auto-selection state not persisting (#611, thanks @yovinchen)
- Automatically apply default color when icon color is not set

### Deep Links

- Support multi-endpoint import (#597, thanks @yovinchen)
- Prefer `GOOGLE_GEMINI_BASE_URL` over `GEMINI_BASE_URL`

### MCP

- Skip `cmd /c` wrapper for WSL target paths (#592, thanks @cxyfer)

### Usage Templates

- Added variable hints, fixed validation issues (#628, thanks @YangYongAn)
- Prevent configuration leakage between providers
- Usage block offset automatically adapts to action button width (#613, thanks @yovinchen)

### Gemini

- Convert timeout parameters to Gemini CLI format (#580, thanks @cxyfer)

### UI

- Fixed Select dropdown rendering issues in `FullScreenPanel`

---

## Notes & Considerations

- **OpenCode is a newly supported app**: OpenCode CLI must be installed first to use related features.
- **Global proxy affects all outbound requests**: including usage queries, health checks, and other network operations.
- **Rectifier is experimental**: can be disabled in Advanced Settings if issues occur.

---

## Special Thanks

Thanks to @yovinchen @YangYongAn @cxyfer @xxk8 @kkkman22 @Shuimo03 for their contributions to this release!
Thanks to @libukai for designing the elegant failover-related UI!

---

## Download & Installation

Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.

### System Requirements

| System  | Minimum Version                 | Architecture                        |
| ------- | ------------------------------- | ----------------------------------- |
| Windows | Windows 10 or later             | x64                                 |
| macOS   | macOS 10.15 (Catalina) or later | Intel (x64) / Apple Silicon (arm64) |
| Linux   | See table below                 | x64 / arm64                         |

### Windows

| File                                     | Description                                          |
| ---------------------------------------- | ---------------------------------------------------- |
| `CC-Switch-v3.10.3-Windows.msi`          | **Recommended** - MSI installer with auto-update     |
| `CC-Switch-v3.10.3-Windows-Portable.zip` | Portable version, extract and run, no registry write |

### macOS

| File                             | Description                                                           |
| -------------------------------- | --------------------------------------------------------------------- |
| `CC-Switch-v3.10.3-macOS.zip`    | **Recommended** - Extract and drag to Applications, Universal Binary |
| `CC-Switch-v3.10.3-macOS.tar.gz` | For Homebrew installation and auto-update                             |

> **Note**: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it, then go to "System Settings" → "Privacy & Security" → click "Open Anyway", and it will open normally afterwards.

### Homebrew (macOS)

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

Update:

```bash
brew upgrade --cask cc-switch
```

### Linux

| Distribution                            | Recommended Format | Installation Method                                                    |
| --------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`             | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`             | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm`  |
| openSUSE                                | `.rpm`             | `sudo zypper install ./CC-Switch-*.rpm`                                |
| Arch Linux / Manjaro                    | `.AppImage`        | Add execute permission and run directly, or use AUR                    |
| Other distributions / Unsure            | `.AppImage`        | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |

### Linux ARM64 (New in v3.10.3)

| File                                     | Description                                                            |
| ---------------------------------------- | ---------------------------------------------------------------------- |
| `CC-Switch-v3.10.3-Linux-arm64.deb`      | For Debian/Ubuntu ARM64 (Raspberry Pi OS, etc.)                        |
| `CC-Switch-v3.10.3-Linux-arm64.rpm`      | For Fedora/RHEL ARM64                                                  |
| `CC-Switch-v3.10.3-Linux-arm64.AppImage` | Universal ARM64 AppImage                                               |

> **Note**: ARM64 AppImage requires `xdg-utils` package for proper desktop integration. Install with your package manager if not present (e.g., `sudo apt install xdg-utils`).