Problem: Launch failure / white screen troubleshooting —— Trove problem library

What you will run into

Double-clicking or launching cc-switch from the command line does nothing, shows a white screen, or crashes.

Three common root causes: missing runtime libraries (webkit etc., see the dependency entry), corrupted config (~/.cc-switch/config.json incompatible with the version), and shared config rewritten (~/.claude.json / ~/.codex/config.toml section structure mismatch).

Why this happens

cc-switch is a Tauri desktop app: missing GUI libraries -> won't start;

it manages the provider section of ~/.claude.json and ~/.codex/config.toml, and when other tools rewrite those shared files' structure, it parses with the old structure and white-screens/crashes.

Starting from a terminal and watching stderr is the fastest way to locate it.

Desktop app startup is three stages: "dependency chain -> config load -> UI render". When shared libraries (webkit/gtk etc.) are missing, the dynamic-linking stage fails outright — you see "double-click does nothing" (the process never even starts).

When the config is corrupted or its structure mismatches, the process starts but parsing fails — the GUI framework can't initialize content, so you see "white screen / crash".

That difference is your locating clue: totally no response = check dependencies first (ldd | grep "not found"), starts but white screen = check the config first.

There's also a hidden risk surface: files like ~/.claude.json are shared by multiple tools;

when another tool rewrites them with its own structure, cc-switch parses with the old structure and crashes — which is exactly why it only touches the provider section and never the plugin-registration section (minimal-write-surface design).

Launching from a terminal and keeping stderr is the fastest locating method, because the error message names the root cause directly: missing library or parse failure.

Step by step

1. Dependency self-check — Required

ldd /usr/bin/cc-switch | grep "not found"

Any output -> missing libraries; sudo apt install -f or install per the dependency entry.

2. Back up the config, then let it rebuild — Required

mv ~/.cc-switch ~/.cc-switch.bak && cc-switch

If it starts normally, migrate the config you need back from .bak.

3. Launch from a terminal and watch the error — Required

cc-switch

Keep the stderr output; the error points straight at the root cause (missing library / config parse failure).

4. Check the shared config sections — Required

python3 -m json.tool ~/.claude.json >/dev/null && echo JSON-OK

Invalid JSON -> the provider section was corrupted; cc-switch only touches the provider section and never the plugin registration section - restore a backup or fix it by hand.

How to confirm it works

cc-switch --version && cc-switch

Version prints and the GUI opens normally = success (no more crash after dependencies are installed).

Other environments

Symptom

Double-click or command-line launch does nothing, white screen, or crashes.

Cause

1. Missing runtime libraries (webkit etc., see symptom 1);
2. ~/.cc-switch/config.json corrupted or incompatible with the version;
3. Shared config rewritten by other tools (~/.claude.json / ~/.codex/config.toml section structure mismatch).

Solution

1. Dependency self-check: ldd /usr/bin/cc-switch | grep 'not found' - output means missing libraries; install with apt.
2. Back up and retry: back up ~/.cc-switch/, then delete it to let it rebuild.
3. Launch from a terminal and watch the error: cc-switch (keep the stderr output).
4. Shared config section anomaly: check the JSON validity of the provider section in ~/.claude.json (cc-switch only touches the provider section, never the plugin registration section).