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

CC Switch v3.13.0

Lightweight Mode, Quota & Balance Visibility, Provider Model Auto-Fetch, Codex OAuth Reverse Proxy, and Tray Per-App Submenus

中文版 → | 日本語版 →

---

Overview

CC Switch v3.13.0 is a major feature release centered on observability, provider workflow ergonomics, and proxy compatibility. It adds inline quota and balance displays across official Claude / Codex / Gemini providers plus Token Plan, Copilot, and third-party balance APIs; introduces a Lightweight Mode that keeps CC Switch running from the system tray without a main window; delivers automatic model discovery via OpenAI-compatible /v1/models across all five supported applications; ships a Codex OAuth reverse proxy for ChatGPT Plus / Pro subscribers; reorganizes the tray menu into per-app submenus; rebuilds the proxy forwarding stack on a Hyper-based client; and overhauls the Skills workflow with discovery, batch updates, and storage-location toggling. Additional improvements include full URL endpoint mode, session-log usage tracking without proxy interception, the Copilot interaction optimizer, a UTF-8 streaming chunk boundary fix for multi-byte output, and a Linux startup UI responsiveness fix.

Release Date: 2026-04-08

Update Scale: 98 commits | 229 files changed | +23,891 / -2,305 lines

---

Highlights

• Lightweight Mode: Tray-only operating mode that destroys the main window on exit to tray and recreates it on demand, reducing CC Switch's desktop footprint to near zero when idle
• Quota & Balance Visibility: Inline quota or balance readout across provider cards — official Claude / Codex / Gemini subscriptions, GitHub Copilot premium interactions, Codex OAuth, Token Plan providers (Kimi / Zhipu GLM / MiniMax), plus official balance queries for DeepSeek, StepFun, SiliconFlow, OpenRouter, and Novita AI
• Provider Model Auto-Fetch: OpenAI-compatible /v1/models discovery across Claude, Codex, Gemini, OpenCode, and OpenClaw provider forms, with grouped dropdown selection and failure-specific error messages
• Codex OAuth Reverse Proxy: ChatGPT Plus / Pro Codex reverse proxy exposed as a new Claude provider card with managed OAuth login and inline subscription quota display (⚠️ Risk Notice)
• Tray Per-App Submenus: Reworked the tray menu into per-application submenus so it never overflows the screen and background provider switching scales to dozens of providers per app
• Skills Discovery & Batch Updates: SHA-256-based skill update detection, per-skill and "Update All" batch actions, public skills.sh search integration, and a storage-location toggle between CC Switch storage and ~/.agents/skills
• Session Workflow Upgrades: Batch session deletion, a directory picker before launching Claude terminal restore, usage import from Claude / Codex / Gemini session logs without proxy interception, precise Codex JSONL parsing, and per-app usage filtering
• OpenCode / OpenClaw Stream Check Coverage: OpenCode detection via npm package mapping, OpenClaw openai-completions support, and the remaining OpenClaw protocol variants — with custom-header passthrough and auth-header detection fixes
• Full URL Endpoint Mode: Provider option that treats base_url as a complete upstream endpoint, unblocking vendors that require nonstandard URL layouts
• Hyper-based Proxy Forwarding Stack: Refactored proxy forwarding onto a Hyper-based client with transparent header forwarding, improved endpoint rewriting, and better support for dynamic upstream endpoints
• Copilot Interaction Optimizer: Request classification and routing logic that reduces unnecessary GitHub Copilot premium interaction consumption
• UTF-8 Stream Chunk Boundary Fix: All four SSE streaming paths now preserve incomplete multi-byte UTF-8 sequences across TCP chunks, eliminating intermittent U+FFFD garbled output via the Copilot reverse proxy
• Linux Startup UI Fix: Fixed the long-standing issue where the window UI couldn't receive clicks on Linux until the user manually maximized and restored the window

---

New Features

Lightweight Mode

A tray-only operating mode that dramatically reduces CC Switch's desktop footprint when idle.

• Destroys the main window on exit-to-tray instead of hiding it, freeing UI resources and memory
• Recreates the window on demand when the user reopens CC Switch from the tray, a deeplink, or single-instance activation
• Integrated into every window-re-show path: normal startup, deeplink, single_instance, tray show_main, and the lightweight-exit round-trip

Quota & Balance Visibility

Added inline quota and balance readouts to provider cards so users can see remaining capacity without leaving the card.

• Official subscriptions: Inline quota display for Claude, Codex, and Gemini official providers
• GitHub Copilot: Premium interactions quota display on the Copilot provider card
• Codex OAuth: ChatGPT Plus / Pro subscription quota inline with the Codex OAuth provider card
• Token Plan providers: Kimi, Zhipu GLM, and MiniMax with corrected quota math and consistent 0% → 100% usage progression
• Third-party balances: Official balance queries for DeepSeek, StepFun, SiliconFlow, OpenRouter, and Novita AI
• Health-check and usage-config buttons are hidden for official providers to keep the card clean

Provider Model Auto-Fetch

Added OpenAI-compatible model discovery to every provider form, removing the manual copy-paste loop for model IDs.

• Queries the configured provider endpoint's /v1/models
• Groups models in the dropdown by category for easier selection
• Failure-specific error messages distinguish network / authentication / endpoint issues
• Supported across all five applications: Claude, Codex, Gemini, OpenCode, and OpenClaw

Codex OAuth Reverse Proxy

Added a reverse proxy path for ChatGPT Plus / Pro subscribers who want to route their Codex OAuth session through CC Switch.

• Managed OAuth login flow with ChatGPT Plus / Pro authentication
• Surfaces as a new Claude provider card type alongside API-key providers
• Inline subscription quota display
• Integrated into the Auth Center with tightened copy, layout, and icon presentation
• Bumped the Codex OAuth preset to the GPT-5.4 model family
• See the ⚠️ Risk Notice below before enabling

Tray Per-App Submenus

Reorganized the tray menu so providers are grouped under each application instead of living in a flat list.

• Per-application submenus for Claude, Codex, Gemini, OpenCode, and OpenClaw
• Prevents the tray menu from overflowing the screen when users have many providers
• Background provider switching scales cleanly to long provider lists

Skills Discovery & Batch Updates

Upgraded the Skills management panel into a complete discovery plus maintenance workflow.

• SHA-256 update detection: Skills are content-hashed so the UI knows exactly which ones have upstream changes
• Per-skill and batch updates: Individual "Update" buttons plus an animated "Update All" batch action
• Storage-location toggle: Switch between CC Switch storage and ~/.agents/skills without losing skill state
• Public registry search: skills.sh search integrated directly into the dialog for discovering community skills

Session Workflow Upgrades

Multiple session management improvements that reduce friction when working with Claude / Codex / Gemini sessions.

• Batch session deletion: Select and delete multiple sessions at once from Session Manager (#1693, thanks @Alexlangl)
• Directory picker before restore: Claude terminal restore now prompts for the working directory up front (#1752, thanks @yovinchen)
• Usage from session logs without proxy: Usage data imported directly from Claude / Codex / Gemini session logs — no proxy interception required
• Precise Codex JSONL parsing: Replaced estimated Codex usage with precise JSONL session-log parsing plus Codex model name normalization for consistent pricing lookup
• Gemini CLI session log integration: Gemini usage now syncs accurately from Gemini CLI session logs
• Per-app usage filtering: Filter the usage dashboard by Claude, Codex, or Gemini independently

OpenCode / OpenClaw Stream Check Coverage

Extended the Stream Check panel to cover the full OpenCode and OpenClaw surface area.

• OpenCode detection via npm package mapping
• Support for the OpenClaw openai-completions protocol
• Support for the remaining three OpenClaw protocol variants
• Edge-case handling for custom-header passthrough, OpenClaw custom auth-header detection, Bedrock error messaging, and OpenCode default baseURL fallback

Full URL Endpoint Mode

Added a provider option that treats base_url as a complete upstream endpoint instead of a base URL with path appending (#1561, thanks @yovinchen).

• Proxy forwarding and Stream Check both honor the full-URL mode
• Unblocks vendors that require nonstandard URL layouts
• Configurable per-provider on the provider form

OpenCode StepFun Step Plan Preset

• Added a StepFun Step Plan provider preset for OpenCode with sensible defaults (#1668, thanks @sky-wang-salvation)

Copilot Interaction Optimizer

Added request classification and routing logic that reduces unnecessary GitHub Copilot premium interaction consumption.

• Classifies incoming requests by intent and weight
• Routes low-value requests away from premium interaction consumption paths
• Designed to extend the usable lifetime of a Copilot subscription

---

Changes

Tray Menu Organization

• Reworked the tray menu into per-application submenus (Claude / Codex / Gemini / OpenCode / OpenClaw)
• Prevents overflow and scales to long provider lists

Proxy Forwarding Stack

Rebuilt the proxy forwarding layer on a Hyper-based HTTP client (#1714, thanks @yovinchen).

• Transparent header forwarding: headers are forwarded without aggressive filtering
• Improved endpoint rewriting logic
• Better support for dynamic upstream endpoints
• Paired with the new Full URL Endpoint Mode to unblock vendors with nonstandard URL layouts

OAuth Auth Center UI Polish

• Tightened the Auth Center copy, layout, and icon presentation so the Codex OAuth login flow feels cleaner and less cluttered

Provider Key Lifecycle & Live Sync

Reworked the additive provider create / rename / duplicate flows so live config writes, cleanup, and rollback stay consistent across OpenCode / OpenClaw and takeover scenarios (#1724, thanks @yovinchen).

• Additive-mode highlight behavior made persistent across refreshes (#1747, thanks @yovinchen)
• Consistent live config writes across OpenCode / OpenClaw
• Rollback behavior preserved when operations fail

Codex OAuth Defaults

• Updated the Codex OAuth preset to the GPT-5.4 model family

---

Bug Fixes

Copilot Authentication & Proxy Compatibility

• Fixed GitHub Copilot authentication regressions (#1854, thanks @Mason-mengze)
• Corrected enterprise and dynamic endpoint handling
• Repaired clipboard verification-code copying on macOS and Linux
• Fixed Responses routing when Copilot-backed Claude providers target OpenAI models (#1735, thanks @Mason-mengze)

UTF-8 Stream Chunk Boundaries

Fixed intermittent garbled output (U+FFFD replacement characters) in Claude Code when multi-byte UTF-8 sequences such as Chinese characters and emoji were split across TCP stream chunks via the Copilot reverse proxy (#1923, thanks @Cod1ng).

• Replaced String::from_utf8_lossy with a new append_utf8_safe helper across all four SSE streaming paths
• Preserves incomplete trailing bytes in a remainder buffer and merges them with the next chunk before decoding
• Not reproducible with direct Copilot connections that pass through raw bytes without format conversion

Fragmented System Prompt Normalization

Fixed strict OpenAI-compatible chat backends (Nvidia, Qwen-style) rejecting requests when converted Claude payloads contained multiple system messages (#1942, thanks @yovinchen).

• Normalized system content into a single leading system message during the Anthropic → OpenAI chat transformation
• Leaves the rest of the message stream unchanged

Streaming Parser Compatibility

• Fixed SSE parsing to accept fields with optional spaces, improving compatibility with non-strict streaming implementations (#1664, thanks @Alexlangl)

Provider Switch State Corruption

• Serialized per-app provider switches to prevent concurrent failover or hot-switch operations from leaving is_current, settings state, and live backup state out of sync

Claude Takeover Live Config Drift

• Fixed provider edits while Claude takeover is active so live settings remain aligned with the latest provider state without breaking takeover restore behavior (#1828, thanks @geekdada)

WebDAV Password Retention & Validation

• Fixed the WebDAV password field so saved credentials remain visible after refresh
• Treated MKCOL 405 responses correctly during connection validation (#1685, thanks @Alexlangl)

Provider Card Action States

• Fixed additive-mode highlight behavior (#1747, thanks @yovinchen)
• Aligned usage display layout across provider cards by always rendering action buttons
• Replaced hard proxy-switch blocking with a warning path
• Disabled unsupported test and usage actions for Copilot and Codex OAuth cards
• Hid usage-config and health-check buttons for official providers
• Removed the hover-push animation from provider cards

Usage Accuracy & Pricing

• Fixed MiniMax quota math and 0% → 100% progression
• Corrected CNY → USD pricing plus missing model definitions
• Improved Gemini session-log syncing accuracy
• Resolved session-based usage entries being shown as unknown providers

Usage Editor & Skills UI Regressions

• Fixed usage query fields being reset while editing extractor code (#1771, thanks @if-nil)
• Corrected broken skills.sh links and empty descriptions
• Fixed auto-query default interval (5 min) and number-input clearing in usage configuration

Chinese Skills Terminology

• Unified Skills-related labels across settings panels in the zh locale so storage and sync options use consistent wording

Environment & Preset Compatibility

• Added Bun global bin detection in CLI scan (#1742, thanks @makoMakoGo)
• Adapted to the oh-my-openagent rename with backward compatibility (#1746, thanks @yovinchen)
• Corrected the OpenCode kimi-for-coding preset (#1738, thanks @makoMakoGo)
• Gated Gemini keychain parsing to macOS only
• Fixed an OpenClaw serializer panic on empty collections (#1724, thanks @yovinchen)

Linux UI Unresponsive on Startup

Fixed a long-standing Linux bug where the window UI (including native title bar buttons) couldn't receive clicks until the user manually maximized and restored the window.

• Root causes: (1) Tauri webview did not acquire keyboard focus after show() on Linux, so the first click was consumed by X11/Wayland click-to-activate (Tauri #10746, wry #637); (2) GTK surface's input region failed to renegotiate on the visible:false → show() path under some WebKitGTK/compositor combinations, leaving the entire window unresponsive
• Mitigations: Set WEBKIT_DISABLE_COMPOSITING_MODE=1 at startup, and added a new linux_fix::nudge_main_window helper that performs set_focus + a ±1px no-op resize ~200ms after show, equivalent to a visually invisible "maximize-and-restore"
• Coverage: Wired into all window-re-show paths — normal startup, deeplink, single_instance, tray show_main, and lightweight-mode exit

Linux Drag Region on Header

• Removed data-tauri-drag-region from the top header bar on Linux to avoid triggering gtk_window_begin_move_drag paths affected by Tauri #13440 under Wayland
• macOS drag behavior is preserved

OpenCode / OpenClaw Stream Check Edge Cases

• Fixed custom-header passthrough
• OpenClaw custom auth-header detection
• Bedrock error messaging
• OpenCode default baseURL fallback handling

---

Documentation

User Manual Refresh

• Updated the EN / ZH / JA user manuals to cover tray submenus, lightweight mode, provider model fetching, session management, workspace files, WebDAV v2 behavior, OpenCode / OpenClaw activation, and other provider workflow improvements

Community & Contribution Docs

• Added CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md
• Added bilingual GitHub issue and PR templates
• Added Dependabot configuration (#1829, thanks @bengbengbalabalabeng) and a stale-bot workflow for inactive issues
• Added a PR / push quality-checks CI workflow

Release Notes Risk Notice Backport

• Added a Copilot reverse proxy risk notice and anchored highlight links in the v3.12.3 release notes across all three languages

---

⚠️ Risk Notice

Codex OAuth Reverse Proxy Disclaimer

The Codex OAuth reverse proxy introduced in this release accesses ChatGPT Plus / Pro Codex services through reverse-engineered OAuth flows. Please be aware of the following risks before enabling this feature:

1. Terms of Service: Using reverse-engineered OAuth flows to access OpenAI services may violate OpenAI's terms of service, which prohibit unauthorized automated access, service reproduction, and circumventing intended access paths.
2. Account Risk: OpenAI may flag unusual usage patterns as suspicious automated activity, potentially resulting in temporary or permanent restrictions on ChatGPT Plus / Pro access.
3. No Guarantee: OpenAI may update its authentication and detection mechanisms at any time, and usage patterns that work today may be flagged in the future.

The GitHub Copilot reverse proxy introduced in v3.12.3 also remains subject to its existing risk notice — see the v3.12.3 release notes for the full disclosure.

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

---

Download & Installation

Visit Releases 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.13.0-Windows.msi	Recommended - MSI installer with auto-update
CC-Switch-v3.13.0-Windows-Portable.zip	Portable version, extract and run, no registry write

macOS

File	Description
CC-Switch-v3.13.0-macOS.dmg	Recommended - DMG installer, drag to Applications, Universal Binary
CC-Switch-v3.13.0-macOS.zip	ZIP archive, extract and drag to Applications, Universal Binary
CC-Switch-v3.13.0-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)

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

Update:

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