# CC Switch v3.15.0

> Claude Desktop becomes a first-class managed surface with third-party provider switching via proxy gateway, role-based model mapping, major reverse-proxy hardening, Codex OAuth live model discovery, and a filter-driven usage dashboard Hero card

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

---

> [!WARNING]
>
> ## Only Official Channels (Please Read)
>
> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Multiple imposter websites have recently been spotted impersonating CC Switch to solicit payments and harvest account credentials, with some users already reporting financial losses. Please only obtain the software through the official channels listed below:
>
> | Channel            | Only Official                                                                  |
> | ------------------ | ------------------------------------------------------------------------------ |
> | Website            | **[ccswitch.io](https://ccswitch.io)**                                         |
> | Source             | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
> | Downloads          | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
> | Author             | **[@farion1231](https://github.com/farion1231)**                               |
> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
>
> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues so we can take down the imposter site as quickly as possible.

---

## Claude Desktop Guide

The headline feature in this release is the **first-class Claude Desktop management panel**. If you already have many providers configured for Claude Code, start here:

**[Use CC Switch to configure, manage, and switch Claude Desktop providers in one place](../user-manual/en/2-providers/2.6-claude-desktop.md)**

The guide walks through one-click import from Claude Code, adding Claude Desktop-specific providers, direct mode vs. model-mapping mode, showing the hidden local-routing toggle, and returning to Claude Desktop's official sign-in mode.

---

## Overview

CC Switch v3.15.0 is a major release following the v3.14.x line, centered on **promoting Claude Desktop to a first-class managed surface**. It ships third-party provider switching through the in-app proxy gateway, role-based model mapping (`sonnet` / `opus` / `haiku`) with a `supports1m` long-context flag, Copilot/Codex OAuth provider reuse, a redesigned Claude Code import flow, app-switcher differentiation between "Claude Code" and "Claude Desktop", and 44 provider presets translated from the Claude Code catalog into the new Claude Desktop surface.

Around proxy reliability, this release performs a systematic hardening pass: P0–P3 patches across routing / lifecycle / retry / failover / rectifier paths; pooled HTTPS connection reuse for non-Anthropic backends to cut per-request latency; cache hit-rate improvements for Codex and OpenAI Responses (emit `prompt_cache_key` only when a real client-provided session identity exists, canonicalize JSON keys in outgoing request bodies plus `tool_call` arguments and `tool_result` content, and thread `session_id` into the usage logger); correct Anthropic ↔ OpenAI `tool_choice` mapping; Vertex AI full URLs are no longer truncated; Gemini request models are now extracted from the URI path; takeover detection is tightened; and IPv6 listen addresses are supported. ChatGPT Codex OAuth providers no longer depend on hardcoded model lists — CC Switch now fetches a live model list from the ChatGPT backend on demand.

Claude Code's model mapping is now role-based (`sonnet` / `opus` / `haiku`) with display names and a new `supports1m` boolean flag, replacing the legacy `[1M]` suffix and decoupling routing decisions from raw model IDs. The usage dashboard adds a **filter-driven Hero card** that exposes cache-normalized real total tokens and cache hit rate, updated live as the active date range / provider / model filters change; paired with a fix for cache-cost semantics and the noisy pricing warning storm that fired on every request. Robustness improvements in the OpenAI Responses API usage parsing path mean missing or malformed upstream `usage` no longer crashes the VSCode Claude Code extension with a `null` output.

The provider ecosystem expands further: new BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, PatewayAI, and Baidu Qianfan Coding Plan partner presets; DouBao Seed is promoted to partner status; and provider cards now surface a "routing support" badge so users can tell at a glance which providers can be served through Local Routing. This release also fixes a long tail of issues across Codex sessions, OAuth, Claude Desktop forms, Linux segfaults, terminal fallbacks, and ships several GitHub Actions dependency bumps.

**Release date**: 2026-05-16

**Stats**: 127 commits | 211 files changed | +17,980 insertions | -2,748 deletions

---

## Highlights

- **Claude Desktop Becomes a First-Class Managed Surface**: Third-party provider switching through the in-app proxy gateway, role-based model mapping (`sonnet` / `opus` / `haiku`) with a `supports1m` long-context flag, Copilot/Codex OAuth provider reuse, and 44 provider presets translated from the Claude Code catalog. Note: 20 Claude Desktop presets now default to direct mode instead of proxy mode — verify connectivity after upgrade if you previously relied on proxy routing.
- **Major Reverse-Proxy Hardening**: P0–P3 lifecycle / retry / failover / rectifier patches; pooled HTTPS reuse for non-Anthropic backends; Codex / Responses cache hit-rate improvements; correct Anthropic ↔ OpenAI `tool_choice` mapping; Vertex AI URL preservation; Gemini path-based model extraction; refined takeover detection; IPv6 listen address support.
- **Provider Ecosystem Expansion**: New BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, PatewayAI, and Baidu Qianfan Coding Plan partner presets; DouBao Seed promoted to partner status; routing-support badges on provider cards.
- **Role-Based Model Mapping with 1M Flag**: Role-based `sonnet` / `opus` / `haiku` routing with display names and a `supports1m` flag replaces the legacy `[1M]` suffix.
- **Codex OAuth Live Model Discovery**: ChatGPT Codex providers fetch the live model list from the ChatGPT backend on demand.
- **Usage Dashboard Filter-Driven Hero**: Surfaces cache-normalized real total tokens and cache hit rate, updated live as date / provider / model filters change.
- **DeepSeek Tool Calls + Zero-Usage Final Delta**: DeepSeek tool calls now return `reasoning_content` alongside `tool_calls` (#2543, thanks @bling-yshs); the final `message_delta` always includes a usage block (even when zero) so strict Anthropic clients no longer crash on `null` (#2485, thanks @Myoontyee).
- **OpenAI Responses API Usage Parsing Robustness**: Missing or malformed upstream `usage` no longer crashes the VSCode Claude Code extension (#2422, thanks @magucas).

---

## Added

### Claude Desktop Third-Party Provider Switching via Proxy Gateway

CC Switch now treats **Claude Desktop** as a first-class managed surface alongside Claude Code / Codex / Gemini / OpenCode / OpenClaw / Hermes.

- New dedicated Claude Desktop panel that brokers third-party providers to Claude Desktop through CC Switch's in-app proxy gateway
- Routing-support badge on cards for providers that need Local Routing
- Role-based model route mapping locked to `sonnet` / `opus` / `haiku`
- Copilot / Codex OAuth providers can be reused in the Claude Desktop panel
- Redesigned Claude Code settings import flow
- App switcher visually distinguishes "Claude Code" from "Claude Desktop", and the app visibility settings use the "Claude Code" label
- 44 Claude Desktop provider presets translated from the Claude Code preset catalog

### Routing Support Badges on Provider Cards

Provider cards in both the Claude Code and Codex panels now show a routing-support badge so users can tell at a glance which providers can be served through Local Routing.

### Codex OAuth Live Model List

ChatGPT Codex providers no longer rely on a hardcoded model selection — CC Switch fetches a **live model list** from the ChatGPT backend on demand.

### Role-Based Model Mapping with 1M Flag

Claude Code model mapping is now role-based (`sonnet` / `opus` / `haiku`) with display names and a `supports1m` boolean flag, replacing the legacy `[1M]` suffix and decoupling routing from raw model IDs.

### Filter-Driven Usage Hero

The usage dashboard's Hero summary is now filter-driven, updating live as the active date range / provider / model filters change; it surfaces **cache-normalized real total tokens** and cache hit rate so the Hero figures line up with the detail list below.

### Provider Form "Save Anyway" Prompt

Softened provider form input validation by turning non-blocking input issues into a "save anyway" prompt, so a harmless field issue no longer blocks saving (#2307, thanks @allenxln).

### Universal Provider Duplicate Action

Added a "duplicate" button for universal providers from the provider list (#2416, thanks @hubutui).

### Persisted Tauri Window State

Window position and size now persist across launches (#2377, thanks @BillSaul).

### Tray Icon Tooltip

The system tray icon now surfaces a status tooltip on hover (#2417, thanks @Coconut-Fish).

### Warp Terminal Session Launch

Added support for launching Warp and executing a saved session inside it (#2466, thanks @tisonkun).

### DeepSeek `reasoning_content` for Tool Calls

DeepSeek tool-call responses now return `reasoning_content` and `tool_calls` together, so callers can render both (#2543, thanks @bling-yshs).

### Baidu Qianfan Coding Plan (Claude Code)

Added a Baidu Qianfan Coding Plan preset (#2322, thanks @jimmyzhuu).

### Compshare Coding Plan Preset (Cross-App)

The Compshare Coding Plan preset now lands across claude / codex / hermes / openclaw.

### Partner Provider Presets

Added **BytePlus**, **Volcengine Agentplan**, **ClaudeAPI**, **ClaudeCN**, **RunAPI**, **RelaxyCode**, and **PatewayAI** partner presets; promoted **DouBao Seed** to partner status (refreshed endpoint and links).

### 44 Claude Desktop Provider Presets

Translated 44 provider presets from the Claude Code preset catalog into the new Claude Desktop panel.

---

## Changed

### 20 Claude Desktop Presets Default to Direct Mode

20 Claude Desktop presets now ship in direct mode instead of routing through the proxy by default, reducing setup friction for users who don't need proxy-specific compatibility shims. If you previously relied on proxy routing for these presets, verify connectivity after upgrading.

### Claude Desktop Operational Notes

Switching a Claude Desktop provider writes CC Switch's managed 3P profile and **requires restarting Claude Desktop** to take effect; proxy-mode providers require CC Switch's Local Routing to stay running while in use.

### Failover / Local Routing Guardrails

Failover controls now require the target app's Local Routing takeover to be enabled before they can be turned on; stopping only the proxy service is blocked while any app still depends on takeover state, preventing the "proxy stopped but the app still thinks takeover is running" inconsistency.

### Usage Accounting Semantics Changed

Usage summaries now report **cache-normalized real total tokens** and **cache hit rate**. Historical token and cost figures may **shift** after deduplication and pricing recalculation — the new numbers are more accurate but will not equal the values reported in earlier versions.

### Provider Preset Rendering Order

Preset lists now render in the author-defined array order, with partners prioritized first, replacing the previous implicit sort.

### Model Mapping Hint Copy Simplified

`modelMappingOffHint` was rewritten as action-oriented copy across zh / en / ja.

### CC Switch Brand Surface Unified to ccswitch.io

All in-app and README "official website" references now point at ccswitch.io as the sole official site; the release notes template also surfaces ccswitch.io.

### Theme Switch Simplified

Removed the circular reveal animation during theme switches; theme changes are now an instant cross-fade.

### Claude Code App Switcher Differentiation

The app switcher visually distinguishes "Claude Code" from "Claude Desktop", and the app visibility settings use the "Claude Code" label.

### CI: Claude Review Upgraded to Opus 4.7

The Claude review GitHub Action is upgraded to Opus 4.7; the prompt is tuned to reduce nitpick noise; a new `@claude` review-only Code Action is added; PR head SHA is pinned for checkout; the `--max-turns 5` limit is removed.

### GitHub Actions Dependency Bumps

- `actions/checkout` 4 → 6 (#2517)
- `pnpm/action-setup` 5 → 6 (#2518)
- `softprops/action-gh-release` 2 → 3 (#2519)
- `actions/stale` 9 → 10 (#2520)

### DeepSeek Presets Switched to V4

DeepSeek presets now ship V4 (flash / pro) with refreshed pricing seeds.

### Codex 1M Context Toggle Hidden in Edit Form

The 1M context-window toggle is no longer surfaced in the Codex provider edit form, reducing the density of knobs that have no effect in current Codex deployments.

### OpenClaudeCode Migrated to MicuAPI Domain

The OpenClaudeCode preset is migrated to the MicuAPI domain; Micu API links are refreshed to `micuapi.ai`.

### CrazyRouter Endpoints Switched to `cn` Subdomain

CrazyRouter preset endpoints now use the `cn` subdomain.

### RelaxyCode Custom Icon

The RelaxyCode preset icon is switched to a custom `relaxcode.png` asset.

### Kimi For Coding Doc URL

The Kimi For Coding website URL is updated to the `/code/docs/` path.

### SiliconFlow International Site Shows USD

The SiliconFlow international site now correctly shows USD for balance display (it previously displayed CNY incorrectly).

---

## Fixed

### OpenAI Responses API Usage Parsing Robustness

Hardened `build_anthropic_usage_from_responses()` and the Responses → Anthropic SSE translator so a missing or malformed upstream `usage` no longer produces `"usage": null` in `message_delta`. This unblocks strict Anthropic clients (notably the VSCode Claude Code extension) that crashed with `Cannot read properties of null (reading 'output_tokens')` against providers such as Codex OAuth and DashScope's `compatible-mode/v1/responses` endpoint. Added OpenAI field-name fallbacks (`prompt_tokens` / `completion_tokens`), null / empty / partial object handling, and preserved cache token fields even when input/output tokens are missing (#2422, thanks @magucas).

### Proxy Reliability Patches (P0–P3)

Multiple rounds of routing / lifecycle / retry / rectifier patches across the request-forwarder paths; extracted a shared `handle_rectifier_retry_failure` helper and a shared `auth_header_value` helper.

### Proxy: Pooled HTTPS Connection Reuse for Non-Anthropic Backends

Non-Anthropic backends now reuse pooled HTTPS connections instead of opening a fresh TLS session per request, materially reducing per-request latency.

### Proxy: Forward Client's Actual HTTP Method

The proxy no longer hard-codes `POST` — it forwards the client's actual HTTP method, so non-POST upstream endpoints (e.g. GET `/v1/models`) now work correctly.

### Proxy: Per-Attempt Counters and `max_retries` Wiring

Client-request counters are moved out of the per-attempt loop; `AppProxyConfig.max_retries` is now correctly wired into the request forwarder.

### Proxy: Failover Decision Refinements

Refined retryable vs. unretryable error classification in the request forwarder.

### Proxy: Takeover Detection Tightening

Takeover detection is tightened; disabling takeover uses fallback restore, so leftover state no longer strands a provider.

### Proxy: Anthropic ↔ OpenAI `tool_choice` Mapping

During format conversion, Anthropic's `tool_choice` is now correctly mapped to the OpenAI Chat nested form.

### Proxy: Gemini Request Model Extracted from URI Path

Gemini request models are now extracted from the URI path (instead of the body), so transformed traffic reports the right model name.

### Proxy: Auth Header Error Handling

`get_auth_headers` now returns `Result` instead of panicking on bad credentials.

### Proxy: IPv6 Listen Address Validation

The Proxy panel now accepts IPv6 listen addresses.

### Proxy: Codex / Responses Cache Hit Rate

Improved cache hit rate for Codex and OpenAI Responses requests by stabilizing cache key derivation: emit `prompt_cache_key` only when the client actually carries a session identity, so unrelated conversations no longer collapse onto a single key; canonicalize (sort) JSON keys in outgoing request bodies and in `tool_call` arguments / `tool_result` content for byte-identical prefix-cache reuse; thread `session_id` into the usage logger for request correlation.

### Proxy: JSON Schema Underscore Fields Preserved

Private-parameter filtering now preserves underscore-prefixed field names inside JSON Schema name maps (`properties`, `patternProperties`, `definitions`, `$defs`), so user-defined schema keys like `_id` and `_meta` pass through the filter intact.

### Proxy: Read Tool Empty Pages

Drop empty pages from `Read` tool inputs so providers no longer reject the request (#2472, thanks @Kwensiu).

### Proxy: Per-Request Hot-Path Trim

Trimmed per-request hot-path work and database wait time.

### Proxy: Real Provider Model Names Under Takeover

Under takeover, the Claude Code menu now exposes the real provider model names instead of a stale alias.

### Proxy: Zero Usage in Final `message_delta`

The final `message_delta` event now always includes a usage block (even when zero) so strict Anthropic clients no longer crash on `null` (#2485, thanks @Myoontyee).

### Proxy: Streaming `message_delta` Deduplication

Deduplicated `message_delta` events that some upstreams emit twice (#2366, thanks @codeasier).

### Proxy: Scoped `reasoning_content` Preserved for Tool Calls

Tool-call paths now correctly preserve the scoped `reasoning_content` field during transformation; Kimi / Moonshot's OpenAI Chat compatibility path keeps the field while generic OpenAI-compatible requests stay free of it (#2367, thanks @codeasier).

### Proxy: Vertex AI Full URL Preserved

Full Vertex AI URLs are no longer truncated during proxy forwarding (#2415, thanks @xpfo-go).

### Proxy: Leading Billing Header Stripped from System Content

Some upstreams prepend a billing-header chunk to the system message; this content is now stripped (#2350).

### Proxy: Claude Auth Strategy Derived from `ANTHROPIC_*` Env Var

The Claude auth strategy is now derived from the actual `ANTHROPIC_*` env variable name rather than an opaque heuristic.

### Third-Party Claude Providers: Disable Model Test

Model probing is disabled for third-party Claude gateways that don't implement `/v1/models` consistently.

### Model-Fetch: `/models` for Anthropic-Compatible Subpath Providers

`/models` discovery now works for Anthropic-compatible subpath providers.

### Copilot: Claude Model IDs Resolved Against Live `/models`

Copilot-backed providers now resolve Claude model IDs against the live `/models` list to avoid stale ID mismatches.

### Codex: Session Title No Longer Pulls in `environment_context`

Codex session title extraction no longer pulls in the `environment_context` noise (#2439, thanks @eclipsehx).

### Codex: Subagent Sessions Hidden

Codex subagent sessions are now hidden from the main session list (#2445, thanks @LanternCX).

### Codex Startup Live Import Duplication

Fixed a duplicate-import bug in the Codex startup live-import path (#2590, thanks @DhruvShankpal).

### Codex Provider Switch No Longer Disturbs History

Switching the active Codex provider no longer changes existing session history (#2349, thanks @SaladDay).

### Codex Usage Log Wording

Corrected a misleading log message for Codex session usage (#2473, thanks @tisonkun).

### Claude: Persist `max` Effort via Env

`max` effort now correctly persists across restart via the env variable (#2493, thanks @makoMakoGo).

### Claude Desktop: Model Route Matching Without `[1M]` Suffix

Route matching no longer requires the legacy `[1M]` suffix.

### Claude Desktop: Provider Form Input Focus Loss

Fixed an input in the Claude Desktop provider form that lost focus while being edited.

### Claude Desktop: Spurious Proxy-Stopped Status Alert

Removed an alert that fired spuriously when the proxy was intentionally stopped.

### Claude Desktop: Empty Toolbar Capsule Hidden

The empty toolbar capsule is now hidden when Claude Desktop is the active app.

### UI: Monitor Badge Icon Centering

Centered the Monitor badge icon in the app switcher.

### Linux: Theme Selection Segfault

Prevented a segfault triggered by selecting a theme on Linux (#2502, thanks @definfo).

### Terminal: iTerm Fallback on Cold Launch

Prevented iTerm from being selected as a fallback on cold launch when it isn't actually installed (#2448, thanks @hulkbig).

### Config: JSON Keys Sorted Alphabetically

Config writes now sort JSON keys alphabetically for deterministic output (#2469, thanks @fuleinist).

### "Import Existing" Made Side-Effect Free

The "import existing" action is now side-effect free (#2429, thanks @xwil1).

### Coding Plan: Zhipu Weekly Tier Named by Reset Time

Corrected the Zhipu weekly tier name to match the actual reset time (#2420, thanks @TuYv).

### DashScope: Usage Parsing Robustness

Hardened DashScope usage parsing so a malformed payload no longer crashes the VSCode Claude Code extension (#2425, thanks @magucas).

### Usage: Deduplicate Proxy and Session-Log Sources

Deduplicated usage records sourced from both the proxy and session logs.

### Usage: Cache Cost Semantics + Pricing Warn Storm

Corrected cache-cost semantics and silenced the noisy pricing warning that fired on every request.

### CI: Frontend Formatting + Linux Clippy Restored

Restored frontend formatting and Linux clippy checks in CI.

### Proxy Test Helper Clippy Warning

Fixed a clippy warning in the proxy test helper.

---

## Removed

### Hermes Agent Usage Tracking Integration

Removed the Hermes Agent usage tracking integration originally planned for this cycle — upstream behavior changes made the integration impractical to maintain. The integration was **never enabled in any released version**; the "zero-cost rendering" bug discovered during its development was fixed before the integration was rolled back.

### Theme Switch Circular Reveal Animation

Removed the circular reveal animation used during theme switches — it stuttered on slower compositors and added little visible value.

### DDSHub Partner Integration

Removed DDSHub as a partner preset and dropped the cross-link blurbs from the READMEs.

---

## Docs

### README Sponsor Refresh (zh / en / ja)

Added BytePlus, ClaudeCN, RunAPI, and PatewayAI sponsor entries; cross-linked BytePlus and Volcengine entries; refreshed the CrazyRouter $2 credit claim flow, the Compshare blurb, the Right Code blurb, and other sponsor logos and listings; flattened the LionCC logo onto a white background; switched the Chinese README's sponsor logo to the Volcengine artwork; added Hermes Agent to the README subtitles.

### Release Notes Template

The release notes template now surfaces `ccswitch.io`.

### Brand Surface

Documented `ccswitch.io` as the sole official website across READMEs and in-app references.

---

## ⚠️ Upgrade Notes

### 20 Claude Desktop Presets Default to Direct Mode

These 20 presets previously routed through the proxy by default and now default to direct mode. If you were using one of these presets pre-upgrade and depended on the proxy path for connectivity (for example because the proxy applies a special rectifier or transformation layer), verify connectivity after upgrading; you can manually switch them back to proxy mode from the CC Switch panel if needed.

### Claude Desktop Operational Constraints

Switching a Claude Desktop provider **requires restarting Claude Desktop** to take effect; proxy-mode providers require CC Switch's Local Routing to stay running while in use — quitting CC Switch or stopping Local Routing will cut off any proxy-mode Claude Desktop providers.

### Failover Requires Takeover Enabled

Before enabling Failover, make sure the target app's Local Routing takeover is enabled, otherwise the Failover control will refuse to start; stopping the proxy service while any app still depends on takeover state is blocked, so you need to disable takeover at the app layer first before stopping the proxy.

### Usage Figures May Diverge from History

Usage summaries now use cache-normalized real total tokens + cache hit rate. Historical token and cost figures may **shift** after deduplication and pricing recalculation — the new numbers are more accurate but will not equal what earlier versions reported.

---

## ⚠️ Risk Notice

This release inherits the risk notices originally introduced in v3.12.3 / v3.13.0 for reverse-proxy-style features.

**GitHub Copilot Reverse Proxy**: Using Copilot's reverse-proxy path may violate GitHub / Microsoft's terms of service. See the [v3.12.3 release notes](v3.12.3-en.md#️-risk-notice) for details.

**Codex OAuth Reverse Proxy**: Using the Codex OAuth reverse proxy with a ChatGPT subscription may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.

**Claude Desktop Third-Party Provider Switching via Proxy Gateway**: Routing Claude Desktop traffic through CC Switch's in-app proxy gateway to a third-party provider exposes those requests to that provider's billing, compliance, and data-retention policies — read the target provider's terms of service before using.

By enabling these features, users **accept all associated risks**. CC Switch is not responsible for any account restrictions, warnings, or service suspensions that result from using these features.

---

## Download & Installation

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

### System Requirements

| OS      | 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 / ARM64                         |

### Windows

| File                                     | Description                                           |
| ---------------------------------------- | ----------------------------------------------------- |
| `CC-Switch-v3.15.0-Windows.msi`          | **Recommended** - MSI installer, supports auto-update |
| `CC-Switch-v3.15.0-Windows-Portable.zip` | Portable, extract and run, no registry writes         |

### macOS

| File                             | Description                                             |
| -------------------------------- | ------------------------------------------------------- |
| `CC-Switch-v3.15.0-macOS.dmg`    | **Recommended** - DMG installer, drag into Applications |
| `CC-Switch-v3.15.0-macOS.zip`    | Extract and drag into Applications, Universal Binary    |
| `CC-Switch-v3.15.0-macOS.tar.gz` | For Homebrew installation and auto-update               |

> macOS builds are Apple code-signed and notarized — install directly.

### Homebrew (macOS)

> 🎉 CC Switch is now available in the official Homebrew cask repository — no need to add a custom tap!

```bash
brew install --cask cc-switch
```

Update:

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

### Linux

> Linux artifacts are published for both **x86_64** and **ARM64** (`aarch64`). The architecture is included in the asset filename — pick the one matching your machine's `uname -m` output:
>
> - `CC-Switch-v3.15.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
> - `CC-Switch-v3.15.0-Linux-arm64.AppImage` / `.deb` / `.rpm`

| Distribution                            | Recommended | Installation                                                           |
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| 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, or use AUR                             |
| Other distros / not sure                | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
