CC Switch v3.14.1

Tray usage visibility, Codex OAuth stability fixes, Skills import/install reliability, and removal of the Hermes config health scanner

中文版 → | 日本語版 →

---

Overview

CC Switch v3.14.1 is a patch release following v3.14.0, focused on Codex OAuth reverse-proxy stability, tray usage visibility, Skills import / install reliability, Gemini session restore paths, and simplifying Hermes configuration health handling.

For the first time, the system tray surfaces cached usage for the current Claude / Codex / Gemini provider directly in its submenus — including subscription summaries and usage-script summaries with color-coded utilization markers. For Chinese coding-plan providers like Kimi / Zhipu / MiniMax, the tray additionally renders a 5-hour + weekly window layout in the 🟢 h12% w80% style (worst utilization drives the emoji), semantically identical to the official subscription badges. Creating a Claude provider whose ANTHROPIC_BASE_URL matches a known coding-plan host now auto-injects meta.usage_script so the tray lights up without opening the Usage Script modal.

Several Codex OAuth reverse-proxy stability issues are addressed this release: client-provided session IDs are now used as both prompt_cache_key and the Codex session header to avoid UUID-driven cache churn; non-streaming Anthropic clients receive proper JSON responses even when the ChatGPT Codex upstream forces OpenAI Responses SSE; and Stream Check now builds probes with the same store: false, encrypted reasoning include, and provider FAST mode setting as production requests, eliminating the "check fails but it actually works" mismatch. Paired with a new explicit FAST mode toggle, users can now opt into service_tier="priority" on Codex OAuth-backed Claude providers, trading latency against ChatGPT quota consumption on their own terms.

Additionally, the in-app Hermes config health scanner and its warning banner are removed (along with the scan_hermes_config_health command, HermesHealthWarning type, and HermesWriteOutcome.warnings payload), refocusing the Hermes surface on active provider display, switching defaults, memory editing, and launching the Hermes Web UI — deep configuration health is now Hermes's own responsibility.

Release Date: 2026-04-23

Update Scale: 13 commits | 48 files changed | +1,883 / -808 lines

---

Highlights

• Tray Usage Visibility: Claude / Codex / Gemini tray submenus show cached usage for the current provider, including subscription and script-based summaries with color markers; refreshes are throttled, limited to visible apps, and synchronized back into React Query (#2184, thanks @TuYv)
• Tray Coding-Plan Usage (Kimi / Zhipu / MiniMax): The tray renders 5-hour + weekly window usage using the 🟢 h12% w80% layout; Claude providers whose base URL matches a known host auto-inject meta.usage_script
• Codex OAuth FAST Mode: New explicit FAST mode toggle for Codex OAuth-backed Claude providers; when enabled, converted Responses requests send service_tier="priority". Off by default (#2210, thanks @JesusDR01)
• Codex OAuth Stability: Fixed reverse-proxy cache routing (#2218, thanks @majiayu000), Responses SSE aggregation (#2235, thanks @xpfo-go), and Stream Check parity with production (#2210, thanks @JesusDR01)
• Hermes Config Health Scanner Removed: Refocuses the Hermes surface on provider management, memory editing, and launching the Web UI — no longer duplicates deep configuration health judgments
• Skills Import / Install Reliability: Import dialog disables actions while pending and deduplicates results by ID (#2211, thanks @TuYv); model quick-set / one-click config applies against the latest form state (#2249, thanks @Coconut-Fish); root-level SKILL.md repo installs are stable (#2231, thanks @santugege)
• Gemini Session Restore Paths: Session scanning reads .project_root metadata and passes the original project directory back into restore flows (#2240, thanks @tisonkun)
• Session / Settings Layout Polish: Hardened the scroll-area viewport with width containment to fix horizontal overflow; tightened app bottom and settings footer spacing (#2201, thanks @Coconut-Fish)

---

Added

Tray Usage Visibility

• System tray submenus now show cached usage for the current Claude / Codex / Gemini provider (#2184, thanks @TuYv)
• Includes subscription quota summaries and usage-script summaries with color-coded utilization markers
• Tray-triggered refreshes are throttled, limited to visible apps, and synchronized back into React Query so the main window and tray share the same usage data

Tray Coding-Plan Usage (Kimi / Zhipu / MiniMax)

• The tray renders 5-hour + weekly window usage for Chinese coding-plan providers
• Uses the same 🟢 h12% w80% two-window layout as official subscription badges (worst utilization drives the emoji color)
• Creating a Claude provider whose ANTHROPIC_BASE_URL matches a known coding-plan host auto-injects meta.usage_script, so the tray lights up without opening the Usage Script modal
• Existing usage_script values are preserved on update, never clobbering user customizations

Codex OAuth FAST Mode

• New explicit FAST mode toggle for Codex OAuth-backed Claude providers (#2210, thanks @JesusDR01)
• When enabled, converted Responses requests send service_tier="priority" for lower latency
• Off by default to avoid unexpectedly increasing ChatGPT quota consumption

---

Changed

Session and Settings Layout Polish

• Hardened the scroll-area viewport with width containment to fix horizontal overflow (#2201, thanks @Coconut-Fish)
• Tightened app bottom and settings footer spacing so long session / settings views fit more cleanly

---

Removed

Hermes Config Health Scanner

• Removed the in-app Hermes config health scanner and its warning banner
• Removed the scan_hermes_config_health command, HermesHealthWarning type, and HermesWriteOutcome.warnings payload
• The CC Switch Hermes surface now focuses on its core job: active provider display, default provider switching, memory editing, and launching the Hermes Web UI for deep configuration

---

Fixed

Codex OAuth Cache Routing

• Use the client-provided session ID as both prompt_cache_key and the Codex session header, preserving explicit cache keys (#2218, thanks @majiayu000)
• Stop generating UUIDs that caused cache-identity churn, stabilizing the ChatGPT Codex reverse-proxy cache identity

Codex OAuth Responses SSE Aggregation

• Non-streaming Anthropic clients now receive proper JSON even when the ChatGPT Codex upstream forces OpenAI Responses SSE (#2235, thanks @xpfo-go)
• CC Switch aggregates the upstream SSE events before running the non-streaming transform

Codex OAuth Stream Check Parity

• Stream Check now builds Codex OAuth probe requests with the same store: false, encrypted reasoning include, and provider FAST mode setting as production proxy traffic (#2210, thanks @JesusDR01)
• Eliminates the "check fails but it actually works" mismatch

Codex Model Extraction

• Reading the model field from Codex config now uses TOML parsing instead of first-line regex matching (#2227, thanks @nmsn)
• Multiline TOML is handled correctly

Model Quick-Set / One-Click Config

• Model quick-set now applies against the latest provider form config (#2249, thanks @Coconut-Fish)
• Fixes stale form state preventing one-click configuration from succeeding

Skills Import Duplicates

• The Skills import dialog disables actions while import is pending (#2211, thanks @TuYv)
• The installed-skills cache deduplicates imported results by ID, preventing double-clicks from adding duplicate installed entries (#2139)

Root-Level Skill Repos

• Skill install and update flows now consistently resolve three source patterns: direct nested paths, install-name recursive search, and repository-root SKILL.md sources (#2231, thanks @santugege)

Gemini Session Restore Paths

• Gemini session scanning now reads .project_root metadata (#2240, thanks @tisonkun)
• Restore flows can pass the original project directory when available

Provider Hover Names

• Provider icons now expose the provider name on hover for inline SVG, image URL, and fallback initials render paths (#2237, thanks @tisonkun)

---

Notes & Caveats

• Hermes Health Scanner Removed: If you were relying on CC Switch to surface deep Hermes YAML configuration issues, switch to the "Launch Hermes Web UI" toolbar button and inspect them in Hermes's own panel. Day-to-day provider management, switching, memory editing, and MCP / Skills sync continue to be handled by CC Switch.
• Codex OAuth FAST Mode Off by Default: Only turn it on if you accept potentially increased ChatGPT quota consumption in exchange for lower latency.
• Tray Cached Usage: Refreshes are throttled and limited to the currently visible app to avoid unnecessary upstream API calls; values are synchronized into React Query so the main window and tray stay in sync.

---

Download & Installation

Visit Releases 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

Windows

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

macOS

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

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

Homebrew (macOS)

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

Update:

brew upgrade --cask cc-switch

Linux

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