cc-switch

What you will run into

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).

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

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).

Step by step

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.

curl -sL -o cc-switch.AppImage https://gh-proxy.com/https://github.com/farion1231/cc-switch/releases/download/v3.20.1/CC-Switch-v3.20.1-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.

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)

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

How to confirm it works

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).

Other environments

• Windows / macOS: official installers for those platforms (this entry only verified the Linux asset structure).
• Pure CLI environment: cannot run the GUI — do not use it; hand-edit ~/.claude.json / ~/.codex/config.toml instead.
• Co-install with other config-rewriting tools: oh-my-claudecode / claude-code-router / claude-mem all touch ~/.claude.json, judged possible-conflict (shared write surface inferred, not tested) — back up first, evaluate one by one.
• Headless server: same as "pure CLI environment", GUI unavailable.

Daily usage

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

# 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

# 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

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

Uninstall & cleanup

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

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

Dependency warnings

• Version: [3.20.1, 3.20.1] locked (2026-08-31 patch-level upgrade retested: deb structure + write-surface string audit consistent with 3.20.0, evidence; GUI not run — no GUI libs, noted honestly).
• 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).

FAQ

• 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.