CC Switch (by farion1231, MIT, ~13k stars) is a cross-platform desktop All-in-One manager: it switches provider/model configurations for Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw and Hermes. It reads and writes each agent's config files directly, switches with one click in the GUI, and also provides session usage stats, skills/MCP management and WebDAV sync.

In one sentence: the "provider switch" tool — no more hand-editing ~/.claude.json and ~/.codex/config.toml.

You use both Claude Code and Codex, each with two or three providers, and every switch means hand-editing config files (~/.claude.json providers, ~/.codex/config.toml model vendor), where one misplaced comma breaks the whole CLI. CC Switch exists for this: a desktop GUI that switches sessions and providers across multiple agents from one place, with usage statistics. At its core it is a "config rewriter" — one click rewrites ~/.claude.json / ~/.codex/config.toml for you. Note: this entry is a desktop GUI; this environment has no GUI libraries so it was not actually run; the install path and write surface are based on binary audit + official docs, marked accordingly.

When to use it:

• Switching between multiple providers/models quickly (click in the GUI);
• Managing Codex config (OpenAI OAuth or third-party providers);
• Viewing session usage statistics across agents.

When not to use it: a single agent with a single provider; or a pure CLI environment (it is a desktop GUI that needs a desktop).

note: AppImage no-install form (structure confirmed here); mainland GitHub direct is slow, must use gh-proxy

# Source: Trove detailed guide · verified 2026-08-31
curl -sL -o cc-switch.AppImage https://gh-proxy.com/https://github.com/farion1231/cc-switch/releases/download/v3.20.0/CC-Switch-v3.20.0-Linux-x86_64.AppImage
chmod +x cc-switch.AppImage && ./cc-switch.AppImage

Expected output: application window (desktop environment)

Because this is a GUI entry (not run in this environment), confirmation has two layers:

• Install layer (machine-verifiable): command -v cc-switch has a path; in AppImage mode the file is executable and ldconfig -p | grep webkit2gtk has output;
• Function layer (desktop verification): after launch, the config panel lists installed agents; do one switch and confirm the corresponding config file was rewritten and the agent CLI starts a session with the new config (per official docs).

It is a desktop app (Linux deb / AppImage / installers for other platforms), with Linux depending on libwebkit2gtk-4.1. The core mechanism is config panel → rewrite the target agent's config file: switching the Claude Code provider rewrites ~/.claude.json, managing Codex rewrites ~/.codex/config.toml; usage statistics persist via SQLite.

Key concepts:

• Provider switching: rewrites the provider config in ~/.claude.json;
• Codex panel: manages ~/.codex/config.toml (OAuth token expiry prompts re-login);
• Usage statistics: per-agent session stats (SQLite persistence).

Where it writes: ~/.cc-switch/ (own data) + ~/.claude.json / ~/.codex/config.toml (rewritten when switching — shared config, back up first).

• Managed surfaces: ~/.claude.json (Claude Code provider), ~/.codex/config.toml (Codex), opencode config, ~/.cc-switch/config.json (its own), SQLite session-usage store
• Form: desktop GUI (Tauri); writes the shared configs listed above when switching

Step 1: Install (deb or AppImage?)

Why: deb suits long-term installs on Debian/Ubuntu (dpkg-managed, uninstallable); AppImage is no-install, download-and-run, good for trying first. Mainland GitHub direct is slow, so download URLs use the gh-proxy prefix. GUI startup needs a desktop environment.

# Source: Trove detailed guide · verified 2026-08-31
curl -sL -o cc-switch.AppImage https://gh-proxy.com/https://github.com/farion1231/cc-switch/releases/download/v3.20.0/CC-Switch-v3.20.0-Linux-x86_64.AppImage
chmod +x cc-switch.AppImage && ./cc-switch.AppImage

Expected output: application window (desktop environment)

After install, confirm:

• the AppImage file is executable and starts into a window (needs a desktop environment);
• dependency check: libwebkit2gtk-4.1 present (ldconfig -p | grep webkit2gtk).

Stuck? How to recover:

• AppImage won't start → ldconfig -p | grep webkit2gtk to confirm libwebkit2gtk-4.1; if missing run apt-get install -y libwebkit2gtk-4.1-0;
• headless environment → a pure CLI environment cannot run the GUI; configure each agent's CLI directly instead;
• GitHub download slow → confirm the download URL has the gh-proxy prefix.

Step 2: Switch providers (write operation, back up first)

Why: this is the core step and the one to be careful about — switching rewrites shared config files. Switching the Claude Code provider = rewriting the provider in ~/.claude.json; managing Codex = rewriting ~/.codex/config.toml. Back up both files first so a wrong switch can be restored.

# Source: Trove detailed guide · verified 2026-08-31
cp ~/.claude.json ~/.claude.json.bak-$(date +%F) 2>/dev/null || true
cp ~/.codex/config.toml ~/.codex/config.toml.bak-$(date +%F) 2>/dev/null || true

Expected output: both config files have date-stamped backups (skipped if already present)

# Source: Trove detailed guide · verified 2026-08-31
# GUI: pick the target provider/model in the config panel → apply

Expected output: the provider config in ~/.claude.json is rewritten (switch takes effect; GUI not verified here, per official docs)

After install, confirm:

• after switching, the target agent CLI works with the new provider (claude / codex starts a session);
• the config file is still valid syntax (python3 -c "import json; json.load(open(\"~/.claude.json\".replace(\"~\", \"$HOME\")))" has no error).

Stuck? How to recover:

• CLI reports config error after switch → restore from backup (cp ~/.claude.json.bak-<date> ~/.claude.json);
• Codex OAuth expired → the GUI prompts re-login; re-authorize as prompted;
• switch did not take effect → confirm the GUI selected the target agent's provider, and the corresponding CLI restarted its session.

Startup and entry

• AppImage: ./cc-switch.AppImage; deb: app menu or cc-switch.
• Panels: config panel (provider switching), Codex panel, usage panel.

Common operations

Operation 1: Switch the Claude Code provider

# Source: Trove detailed guide · verified 2026-08-31
# GUI: pick the target provider/model in the config panel → apply

Expected output: the provider config in ~/.claude.json is rewritten (switch takes effect)

Operation 2: Manage Codex config

# Source: Trove detailed guide · verified 2026-08-31
# GUI: add a provider in the Codex panel (OpenAI OAuth or third-party)

Expected output: ~/.codex/config.toml is managed (OAuth token expiry prompts re-login)

Operation 3: View session usage

# Source: Trove detailed guide · verified 2026-08-31
# GUI: usage panel

Expected output: per-agent (Claude/Codex/Gemini/OpenCode etc.) session statistics (SQLite persistence)

Data and directories

• Own data: ~/.cc-switch/ (includes usage statistics SQLite);
• Shared config (rewritten when switching): ~/.claude.json, ~/.codex/config.toml.

Same source as the tool-page matrix — 19 pairs total (0 measured compatible / 15 inferred possibly compatible / 4 inferred possibly conflicting); full pairs, states and evidence: Conflict pairs (co-install matrix).

• Symptom: dpkg -i missing dependencies: libwebkit2gtk etc. (Linux install/launch failure)
• Symptom: GitHub Release download TLS drops / timeout
• Symptom: architecture mismatch (ARM devices such as Orange Pi)
• Symptom: launch failure / blank screen
• Symptom: install-source confusion: same-name npm package / other cc-switch projects
• Symptom: shared configs not restored after uninstall (~/.claude.json / ~/.codex/config.toml)

Full four-part write-up (symptom → cause → fix → verification evidence): site docs

# Source: Trove detailed guide · verified 2026-08-31
sudo dpkg -r cc-switch 2>/dev/null || true; rm -rf ~/.cc-switch

note: uninstall via dpkg; note that ~/.claude.json and ~/.codex/config.toml are shared config and uninstall does not restore them

# Source: Trove detailed guide · verified 2026-08-31
sudo dpkg -r cc-switch 2>/dev/null || true
rm -rf ~/.cc-switch
command -v cc-switch >/dev/null 2>&1 && echo '残留: cc-switch 仍存在' || echo 'cc-switch removed: OK'

Expected output: cc-switch removed: OK

• Runtime precheck (Linux x86_64 desktop; depends on libwebkit2gtk-4.1)
• Official release assets (structure confirmed in this environment); direct GitHub downloads are slow in China, gh-proxy acceleration required
• GUI operation; each item = target + expected result; official docs ccswitch.io (English/Chinese)
• dpkg uninstall; note ~/.claude.json and ~/.codex/config.toml are shared configs, uninstall does not restore them
• Shared write surface: it rewrites ~/.claude.json and ~/.codex/config.toml — same-surface rewrite risk with omc (Claude plugin registration), claude-code-router (routing config) (judged possible-conflict in this marketplace); back up both files before switching

• Q: GUI won't start? A: confirm a desktop environment and libwebkit2gtk-4.1 (ldconfig check); a pure headless environment cannot run the GUI.
• Q: What does switching change? A: it rewrites the provider config in ~/.claude.json (Claude Code) and ~/.codex/config.toml (Codex); back up both files before switching.
• Q: Can it be installed alongside claude-code-router / claude-mem? A: all three touch the ~/.claude.json write surface; currently judged possible-conflict (shared write surface inferred, not tested); back up first and evaluate one by one.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.

• Version: [3.20.0, 3.20.0] locked (version confirmed at collection via structure).
• Environment: Linux x86_64 desktop; depends on libwebkit2gtk-4.1; AppImage is no-install but still needs a desktop environment.
• Network: mainland GitHub direct is slow, must use the gh-proxy prefix (verified path).
• Write surface (large): ~/.cc-switch/ + shared config ~/.claude.json, ~/.codex/config.toml — switching rewrites shared config, back up first.
• Co-install: with oh-my-claudecode / claude-code-router / claude-mem judged possible-conflict (shared ~/.claude.json write surface inferred, not tested).

• Verified: local repro log (2026-08-28, release asset structure confirmed: deb/AppImage download URLs and version).
• Not tested: GUI run and switching operations (no GUI libraries in this environment) — expected behavior from the official docs, marked accordingly.

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方 README：Quick Start（Add Provider / Switch / 生效 / 回官方） [官方文档 · cc-switch 官方 · 2026-08-30（v3.20.1 抓取）]
  4 步核心用法——添加供应商（预设或自定义）→ 主界面/托盘切换 → 重启终端或 CLI 生效（Claude Code 免重启）→ 用「官方登录」预设回官方账号
• 官方 README：MCP / Prompts / Skills / Sessions 用法 [官方文档 · cc-switch 官方 · 2026-08-30（v3.20.1 抓取）]
  进阶能力——MCP 服务器添加（模板/自定义/按应用同步）、Prompts 预设（Markdown 编辑器 + 激活同步）、Skills 一键安装（浏览 GitHub 仓库）、Sessions 会话浏览/搜索/恢复
• 官方 README：Download & Installation（系统要求/平台差异） [官方文档 · cc-switch 官方 · 2026-08-30（v3.20.1 抓取）]
  Windows（安装包/便携版）、macOS（dmg）、Arch Linux（AUR/手动）、Linux（deb/rpm/AppImage）四平台安装路径