cc-switch/docs/release-notes/v3.12.3-en.md

# CC Switch v3.12.3

> GitHub Copilot Reverse Proxy, macOS Code Signing & Notarization, Reasoning Effort Mapping, OpenCode SQLite Backend

**[中文版 →](v3.12.3-zh.md) | [日本語版 →](v3.12.3-ja.md)**

---

## Overview

CC Switch v3.12.3 is a major feature release that adds GitHub Copilot reverse proxy support with a dedicated Auth Center, introduces macOS code signing and Apple notarization for a seamless install experience, maps reasoning effort levels across providers, migrates OpenCode to a SQLite backend, enables Tool Search via the native `ENABLE_TOOL_SEARCH` environment variable toggle, and delivers a full skill backup/restore lifecycle. Additional improvements include proxy gzip compression, o-series model compatibility, Skills import rework, Ghostty terminal fix, Skills cache strategy optimization, Claude 4.6 context window update, and multiple bug fixes.

**Release Date**: 2026-03-24

**Update Scale**: 36 commits | 107 files changed | +9,124 / -802 lines

---

## Highlights

- **GitHub Copilot reverse proxy**: Full Copilot proxy support with OAuth device flow authentication, token refresh, and request fingerprint emulation ([⚠️ Risk Notice](#️-risk-notice))
- **Copilot Auth Center**: Dedicated authentication management UI for GitHub Copilot OAuth flow with token status display and one-click refresh
- **macOS code signing & notarization**: macOS builds are now code-signed and notarized by Apple, eliminating the "unidentified developer" warning entirely
- **Reasoning Effort mapping**: Proxy-layer auto-mapping — explicit `output_config.effort` takes priority, falling back to `budget_tokens` thresholds (<4 000→low, 4 000–16 000→medium, ≥16 000→high) for o-series and GPT-5+ models
- **OpenCode SQLite backend**: Added SQLite session storage for OpenCode alongside existing JSON backend; dual-backend scan with SQLite priority on ID conflicts
- **Codex 1M context window toggle**: One-click checkbox to set `model_context_window = 1000000` with auto-populated `model_auto_compact_token_limit`
- **Disable Auto-Upgrade toggle**: Added `DISABLE_AUTOUPDATER` env var checkbox in the Claude Common Config editor to prevent Claude Code from auto-upgrading
- **Tool Search env var toggle**: Tool Search enabled via Claude 2.1.76+ native `ENABLE_TOOL_SEARCH` environment variable in the Common Config editor — no binary patching required
- **Skill backup/restore lifecycle**: Skills are automatically backed up before uninstall; backup list with restore and delete management added
- **Proxy gzip compression**: Non-streaming proxy requests now auto-negotiate gzip compression, reducing bandwidth usage
- **o-series model compatibility**: Chat Completions proxy correctly uses `max_completion_tokens` for o1/o3/o4-mini models; Responses API kept on the correct `max_output_tokens` field
- **Skills import rework**: Replaced implicit filesystem-based app inference with explicit `ImportSkillSelection` to prevent incorrect multi-app activation
- **Ghostty terminal support**: Fixed Claude session restore in Ghostty terminal

---

## New Features

### GitHub Copilot Reverse Proxy

Added full reverse proxy support for GitHub Copilot, enabling Copilot-authenticated requests to be forwarded through CC Switch.

- Implements OAuth device flow authentication for GitHub Copilot
- Automatic token refresh and session management
- Request fingerprint emulation for seamless compatibility
- Integrated into the existing proxy infrastructure alongside Claude, Codex, and Gemini handlers

### Copilot Auth Center

A dedicated authentication management UI for GitHub Copilot.

- OAuth device flow with code display and browser-based authorization
- Token status display showing expiration and validity
- One-click token refresh without re-authentication
- Integrated into the settings panel for easy access

### Reasoning Effort Mapping

Proxy-layer auto-mapping of reasoning effort for OpenAI o-series and GPT-5+ models.

- Two-tier resolution: explicit `output_config.effort` takes priority, falling back to thinking `budget_tokens` thresholds (<4 000→low, 4 000–16 000→medium, ≥16 000→high)
- Covers both Chat Completions and Responses API paths with 17 unit tests

### OpenCode SQLite Backend

Added SQLite session storage support for OpenCode alongside the existing JSON backend.

- Dual-backend scan with SQLite priority on ID conflicts
- Atomic session deletion and path validation
- JSON backend remains functional for backwards compatibility

### Codex 1M Context Window Toggle

Added a one-click toggle for Codex 1M context window in the config editor.

- Checkbox sets `model_context_window = 1000000` in `config.toml`
- Auto-populates `model_auto_compact_token_limit = 900000` when enabled
- Unchecking removes both fields cleanly

### Disable Auto-Upgrade Toggle

Added a checkbox in the Claude Common Config editor to disable Claude Code auto-upgrades.

- Sets `DISABLE_AUTOUPDATER=1` in the environment configuration when enabled
- Displayed alongside Teammates mode, Tool Search, and High Effort toggles

### Tool Search Environment Variable Toggle

Tool Search is now enabled via the native `ENABLE_TOOL_SEARCH` environment variable introduced in Claude 2.1.76+.

- Toggle available in the Common Config editor under environment variables
- Sets `ENABLE_TOOL_SEARCH=1` in the Claude environment configuration
- No binary patching required — uses Claude's built-in support

### macOS Code Signing & Notarization

macOS builds are now code-signed and notarized by Apple.

- Application signed with a valid Apple Developer certificate
- Notarized through Apple's notarization service for Gatekeeper approval
- DMG installer also signed and notarized
- Eliminates the "unidentified developer" warning on first launch

### Skill Auto-Backup on Uninstall

Skill files are now automatically backed up before uninstall to prevent accidental data loss.

- Backups stored in `~/.cc-switch/skill-backups/` with all skill files and a `meta.json` containing original metadata
- Old backups are automatically pruned to keep at most 20
- Backup path is returned to the frontend and shown in the success toast

### Skill Backup Restore & Delete

Added management commands for skill backups created during uninstall.

- List all available skill backups with metadata
- Restore copies files back to SSOT, saves the DB record, and syncs to the current app with rollback on failure
- Delete removes the backup directory after a confirmation dialog
- ConfirmDialog gains a configurable zIndex prop to support nested dialog stacking

---

## Changes

### Skills Cache Strategy Optimization

Optimized the Skills cache invalidation strategy for better performance.

- Reduced unnecessary cache refreshes during skill operations
- Improved cache coherence between skill install/uninstall and list queries

### Claude 4.6 Context Window Update

Updated Claude 4.6 model preset with the latest context window size.

- Reflects the expanded context window for Claude 4.6 models
- Updated in provider presets for accurate model information display

### MiniMax M2.7 Upgrade

- Updated MiniMax provider preset to M2.7 model variant

### Xiaomi MiMo Upgrade

- Updated Xiaomi MiMo provider preset to the latest model version

### AddProviderDialog Simplification

- Removed redundant OAuth tab, reducing dialog from 3 tabs to 2 (app-specific + universal)

### Provider Form Advanced Options Collapse

- Model mapping, API format, and other advanced fields in the Claude provider form now auto-collapse when empty
- Auto-expands when any value is set or when a preset fills them in; does not auto-collapse when manually cleared

### Proxy Gzip Compression

Non-streaming proxy requests now support gzip compression for reduced bandwidth usage.

- Non-streaming requests let reqwest auto-negotiate gzip and transparently decompress responses
- Streaming requests conservatively keep `Accept-Encoding: identity` to avoid decompression errors on interrupted SSE streams

### o1/o3 Model Compatibility

Proxy forwarding now handles OpenAI o-series model token parameters correctly.

- Chat Completions path uses `max_completion_tokens` instead of `max_tokens` for o1/o3/o4-mini models (#1451, thanks @Hemilt0n)
- Responses API path kept on the correct `max_output_tokens` field instead of incorrectly injecting `max_completion_tokens`

### OpenCode Model Variants

- Placed OpenCode model variants at top level instead of inside options for better discoverability (#1317)

### Skills Import Flow

The Skills import flow has been reworked for correctness and cleanup.

- Replaced implicit filesystem-based app inference with explicit `ImportSkillSelection` to prevent incorrect multi-app activation when the same skill directory exists under multiple app paths
- Added reconciliation to `sync_to_app` to remove disabled/orphaned symlinks
- MCP `sync_all_enabled` now removes disabled servers from live config
- Schema migration preserves a snapshot of legacy app mappings to avoid lossy reconstruction

---

## Bug Fixes

### WebDAV Password Clearing

- Fixed an issue where the WebDAV password was silently cleared when saving unrelated settings

### Tool Message Parsing

- Fixed incorrect parsing of tool-use messages in certain proxy response formats

### Dark Mode Styling

- Fixed dark mode rendering inconsistencies in UI components

### Copilot Request Fingerprint

- Fixed request fingerprint generation for Copilot proxy to match expected format

### Provider Form Double Submit

- Prevented duplicate submissions on rapid button clicks in provider add/edit forms (#1352, thanks @Hexi1997)

### Ghostty Session Restore

- Fixed Claude session restore in Ghostty terminal (#1506, thanks @canyonsehun)

### Skill ZIP Import Extension

- Added `.skill` file extension support in ZIP import dialog (#1240, #1455, thanks @yovinchen)

### Skill ZIP Install Target App

- ZIP skill installs now use the currently active app instead of always defaulting to Claude

### OpenClaw Active Card Highlight

- Fixed active OpenClaw provider card not being highlighted (#1419, thanks @funnytime75)

### Responsive Layout with TOC

- Improved responsive design when TOC title exists (#1491, thanks @West-Pavilion)

### Import Skills Dialog White Screen

- Added missing TooltipProvider in ImportSkillsDialog to prevent runtime crash when opening the dialog

### Panel Bottom Blank Area

- Replaced hardcoded `h-[calc(100vh-8rem)]` with `flex-1 min-h-0` across all content panels to eliminate bottom gap caused by mismatched offset values on different platforms

---

## Documentation

### Pricing Model ID Normalization

- Added documentation section explaining model ID normalization rules (prefix stripping, suffix trimming, `@`→`-` replacement) in EN/ZH/JA user manuals (#1591, thanks @makoMakoGo)

### macOS Signed Build Messaging

- Removed all `xattr` workaround instructions and "unidentified developer" warnings from README, README_ZH, installation guides (EN/ZH/JA), and FAQ pages (EN/ZH/JA); replaced with "signed and notarized by Apple" messaging

---

## ⚠️ Risk Notice

**GitHub Copilot Reverse Proxy Disclaimer**

The Copilot reverse proxy feature introduced in this release accesses GitHub Copilot services through reverse-engineered, unofficial APIs. Please be aware of the following risks before enabling this feature:

1. **Terms of Service**: This feature may violate [GitHub's Acceptable Use Policies](https://docs.github.com/en/site-policy/acceptable-use-policies/github-acceptable-use-policies) and [Terms for Additional Products and Features](https://docs.github.com/en/site-policy/github-terms/github-terms-for-additional-products-and-features), which prohibit excessive automated bulk activity, unauthorized service reproduction, and placing undue burden on servers through automated means.
2. **Account Risk**: There are documented cases of GitHub issuing warning emails to users of similar tools, citing "scripted interactions or otherwise deliberately unusual or strenuous" usage patterns. Continued use after a warning may result in temporary or permanent suspension of Copilot access.
3. **No Guarantee**: GitHub may update its detection mechanisms at any time, and usage patterns that work today may be flagged in the future.

Users enable this feature **at their own risk**. CC Switch is not responsible for any account restrictions, warnings, or service suspensions resulting from the use of this feature.

---

## 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 12 (Monterey) or later    | Intel (x64) / Apple Silicon (arm64) |
| Linux   | See table below                 | x64                                 |

### Windows

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

### macOS

| File                               | Description                                                          |
| ---------------------------------- | -------------------------------------------------------------------- |
| `CC-Switch-v3.12.3-macOS.dmg`     | **Recommended** - DMG installer, drag to Applications, Universal Binary |
| `CC-Switch-v3.12.3-macOS.zip`     | ZIP archive, extract and drag to Applications, Universal Binary      |
| `CC-Switch-v3.12.3-macOS.tar.gz`  | For Homebrew installation and auto-update                            |

> macOS builds are code-signed and notarized by Apple for a seamless install experience.

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