Install CC Switch: Manage Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw & Hermes Agent from One App (2026)

What You Can Do After This Setup, In 30 Seconds

If you’re already on CC Switch and looking for a specific problem — config file not picked up, OAuth re-login loop, Codex wire_api mismatch — jump to Common Errors During Setup below. Otherwise, the next four sections walk through install → first provider → verify → multi-CLI in order.

System Requirements

CC Switch is a Tauri 2 desktop app — small (~10 MB installer), but it does need a graphical session and the right CLI runtimes underneath. Check each row before you start, because most “CC Switch isn’t working” reports trace back to a missing CLI rather than the app itself.

You don’t have to install every CLI up front — CC Switch only manages the panels you actually have on disk. Start with the one or two you use most.

Step 1 — Install CC Switch

Pick the platform-native path. Don’t mix Homebrew and manual download on macOS; auto-update only tracks one channel.

macOS (Homebrew)

brew install --cask cc-switch
# upgrade later with:
brew upgrade --cask cc-switch

The cask is signed and notarized by Apple — first launch opens directly without a Gatekeeper prompt.

macOS (manual .dmg)

# Download the latest DMG from the Releases page, then:
open CC-Switch-v3.16.1-macOS.dmg
# Drag CC Switch.app to /Applications

Windows

Download CC-Switch-v3.16.1-Windows.msi from github.com/farion1231/cc-switch/releases and double-click. A portable CC-Switch-v3.16.1-Windows-Portable.zip is available if your machine blocks MSI installs.

Linux (Debian / Ubuntu)

# x86_64 example
sudo dpkg -i CC-Switch-v3.16.1-Linux-x86_64.deb
# If apt complains about dependencies:
sudo apt-get install -f

Linux (Arch)

paru -S cc-switch-bin   # or: yay -S cc-switch-bin

Linux (universal AppImage)

chmod +x CC-Switch-v3.16.1-Linux-x86_64.AppImage
./CC-Switch-v3.16.1-Linux-x86_64.AppImage

Headless servers / CI

The Tauri 2 desktop app needs Wayland or X11. For headless boxes — build runners, remote sandboxes — use the Rust CLI fork SaladDay/cc-switch-cli instead. It reads the same WebDAV-synced config bundle, so you can author providers on a laptop and pull them down on the agent.

Verify the install

After first launch:

1. The CC Switch window opens to the Claude Code panel by default.
2. A CC Switch icon appears in the system tray (menu bar on macOS, system tray on Windows/Linux).
3. The top-left app switcher lists the seven managed targets — Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw, Hermes Agent. Greyed-out entries are CLIs CC Switch couldn’t detect on disk; that’s expected if you haven’t installed them yet.

If the tray icon is missing on Linux, your DE may not support StatusNotifierItem; install gnome-shell-extension-appindicator (GNOME) or equivalent and restart the session.

Step 2 — Install the CLIs You’ll Manage

CC Switch doesn’t install the CLIs themselves — it manages their config files. Install whichever you need:

# All seven, for reference. Pick what you actually use.
npm install -g @anthropic-ai/claude-code   # Claude Code (Node 18+)
npm install -g @openai/codex               # Codex (Node 16+)
npm install -g @google/gemini-cli          # Gemini CLI (Node 20+)
npm install -g opencode-ai                 # OpenCode (no engine floor)
npm install -g openclaw                    # OpenClaw (Node 22.19+)
npm install -g hermes-agent                # Hermes Agent (Node 20+)

Claude Desktop is the standalone Anthropic app — download from claude.ai/download rather than npm.

If npm install -g fails with EACCES or the new shim isn’t on PATH, see our walkthrough on npm global install permission and PATH fixes for Codex CLI — the same fixes apply to every CLI on this list.

Step 3 — Add Your First Provider

Open CC Switch and click the + in the top-right corner. The Add Provider panel has two tabs:

• App-specific Provider — only for the panel you’re on right now
• Universal Provider — shared across Claude Code, Codex, and Gemini CLI

For the first run, use App-specific:

1. From the Preset dropdown, pick the provider that issued your key. CC Switch ships with ~50 third-party presets across all panels: DeepSeek, Zhipu GLM, MiniMax, Kimi, Bailian (Alibaba Qwen), AWS Bedrock, NVIDIA NIM, OpenRouter, plus a long list of relay services. Most just need the API key — the endpoint URL and protocol fields are pre-filled.
2. Paste your API Key.
3. (Codex only) If the preset is marked “Needs Local Routing” — that’s any chat-completions backend like DeepSeek or Zhipu — CC Switch turns on the Local Routing toggle for you, which proxies Codex’s Responses API protocol down to the provider’s /v1/chat/completions. Don’t disable it; Codex 0.137.0 has dropped support for wire_api = "chat" at config-load time and only accepts responses.
4. Click Add.

What each preset actually writes

The preset list is the convenience layer. Underneath, CC Switch writes the CLI’s native config file:

The principle is “minimal intrusion” — even if you uninstall CC Switch tomorrow, every CLI still works because their native config files are intact. CC Switch’s own state in ~/.cc-switch/cc-switch.db is purely additive.

Step 4 — Switch and Verify

Once you have at least one provider per CLI:

• From the app: click the provider card, then Enable.
• From the system tray (the genuinely useful part): right-click the CC Switch icon → pick a CLI panel → click a provider name. The new config is written before the menu closes.

Then activate it on the CLI side:

Quick sanity test inside each CLI’s session:

> Hello — which model am I talking to right now?

A reasonable model identification confirms both that the key is valid and that the routing is correct.

Common Errors During Setup (and Fixes)

If your CLI complains about its own config — model_not_found, EACCES, 429, 503 — that’s the CLI’s problem, not CC Switch’s. For Codex specifically, the install-time command not found failure mode is covered in Codex command not found: 7 fixes after npm install -g. Each CLI has its own runtime-error runbook; CC Switch only manages the config file, not the request path.

Team / Multi-Developer Configuration

The pain CC Switch actually solves is teams that share third-party keys across multiple agents — not the solo dev with one CLI. Three patterns scale.

Pattern 1 — Universal Provider for a shared relay key

If your team uses a single OpenAI-compatible relay (one base URL, one shared key) across Claude Code, Codex, and Gemini CLI, the Universal Provider tab is the right tool. Add it once with the relay’s endpoint and key, check the boxes for the three apps to sync to, and CC Switch writes the same key to each CLI’s native config file. When the relay rotates the key, you update one row and click Save and Sync — every CLI on every laptop picks it up on next switch.

Pattern 2 — WebDAV-synced config bundle for laptop + CI

Set up a WebDAV server (Nextcloud, self-hosted, whatever your team already has) and point Settings → Storage → custom config directory at it. Authors create providers on their laptops; CI runners using SaladDay/cc-switch-cli pull the same SQLite snapshot. Don’t sync ~/.cc-switch/cc-switch.db through a vanilla Dropbox/iCloud folder — those will happily overwrite the database mid-write if two devices push at the same time. WebDAV with proper locking is the safer transport for the database file specifically.

Pattern 3 — Per-machine override for an on-call engineer

If one engineer needs to test a different provider without affecting the rest of the team, the device-level ~/.cc-switch/settings.json overrides for claudeConfigDir, codexConfigDir, etc. point that engineer’s CC Switch at a non-shared config directory. The team’s WebDAV bundle stays untouched; the override evaporates when they revert the setting.

For all three, treat ~/.cc-switch/cc-switch.db like ~/.ssh/ — it’s not encrypted at rest, so the file’s protection is filesystem permissions plus whatever transport you sync it over.

Advanced — MCP, Skills, Prompts, and OAuth Reuse

Once switching providers is solved, the unified panels are where CC Switch starts pulling its weight.

Unified MCP across five CLIs

Open the MCP button on any panel. CC Switch reads the MCP server list from each CLI’s native location — ~/.claude.json for Claude Code, [mcp_servers.*] blocks in ~/.codex/config.toml, mcpServers in ~/.gemini/settings.json, and the equivalents in OpenCode and Hermes — and lets you toggle each server’s presence per CLI. Add an mcp-fetch server once, sync it to Claude Code + Codex + Gemini, and every agent has the same tool surface.

Prompts (CLAUDE.md / AGENTS.md / GEMINI.md)

The Prompts panel is a Markdown editor with cross-app sync. Edit one prompt in CC Switch, sync to ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, and ~/.gemini/GEMINI.md in one click. Backfill protection means edits made directly in the live files are pulled back into CC Switch before the next sync overwrites them — useful if a teammate edited CLAUDE.md directly.

Skills

The Skills panel installs skills from GitHub repos or ZIP files into each CLI’s skills directory (~/.claude/skills/, ~/.config/opencode/skills/, etc.). Symlink mode is the default — one canonical copy lives in ~/.cc-switch/skills/ and the CLIs see it via symlink. Switch to file-copy mode if your CLI is sandboxed and doesn’t follow symlinks.

Codex OAuth reverse proxy (since v3.13)

CC Switch added a path that reuses your ChatGPT account’s Codex entitlement inside Claude Code. It shows up as a new Claude provider card type — not as a Codex preset — and routes Claude Code’s requests through a local proxy fronting chatgpt.com and auth.openai.com. Useful if you already pay for ChatGPT Plus or Pro. Read the in-app risk notice before relying on it for production; it’s an unofficial reuse path and could break the day OpenAI tightens auth.

Alternatives — When You Don’t Want a Desktop App

Two paths cover the cases where the Tauri desktop app isn’t a fit.

• Single OpenAI-compatible gateway — If you just want one base URL that Claude Code, Codex, Cursor, Cline, and OpenClaw can all point at, OfoxAI exposes https://api.ofox.ai/v1 as a unified OpenAI-compatible endpoint. Most teams reach for this when they want to avoid editing per-CLI configs at all; see the Claude Code integration guide for the one-line setup. You can keep CC Switch for tray-level switching and use ofox as the underlying provider, or skip CC Switch entirely if a single endpoint is enough.
• Headless / scripted environments — SaladDay/cc-switch-cli is a Rust CLI fork that does provider switching, MCP management, skills install, and local proxy from the terminal. Same WebDAV-compatible storage format as the desktop app. Best fit for build agents, remote dev containers, and tmux-only servers.
• Browser UI — Laliet/cc-switch-web is a community web-based alternative covering Claude Code, Codex, and Gemini CLI. Less feature-complete than the desktop app today, but useful if you want a shared URL the whole team opens.

How to Monitor and Stay Current

• Auto-updater — Settings → About → Check for updates. The desktop app auto-checks on launch.
• Release feed — Subscribe to github.com/farion1231/cc-switch/releases. Recent shipped changes worth tracking: Claude Desktop as a first-class panel, the Codex OAuth reverse proxy (v3.13), unified Skills install from GitHub (added pre-v3.16), and per-app usage dashboards.
• Backup hygiene — ~/.cc-switch/backups/ keeps the 10 most recent SQLite snapshots automatically. Before any major version upgrade, cp ~/.cc-switch/cc-switch.db ~/.cc-switch/cc-switch.db.bak.$(date +%F) — a manual snapshot survives the rolling window.

FAQ

The frontmatter faq block above holds the canonical answers; the questions there mirror the People Also Ask cluster for cc switch claude code install, ccswitch install npm, and related queries. Skim those — they cover supported CLI scope, terminal-restart behavior, fork landscape, official-account coexistence, the Codex OAuth reverse-proxy mode, key storage, headless support, and the hand-editing comparison.

Sources Checked for This Refresh

• farion1231/cc-switch README — verified the seven-CLI scope and v3.16.1 release date (verified 2026-06-05)
• cc-switch User Manual — installation guide and provider config formats — verified the per-CLI config file paths and “Needs Local Routing” Codex behavior
• cc-switch FAQ — 5.1 Configuration Files — verified the SQLite paths and per-CLI native config locations
• npm registry — npm view <pkg> version engines on @anthropic-ai/[email protected], @openai/[email protected], @google/[email protected], [email protected], [email protected], [email protected] — confirmed published versions and Node engine floors (verified 2026-06-05)
• SaladDay/cc-switch-cli and Laliet/cc-switch-web — confirmed the WebDAV-compatible storage and supported-CLI scope for both forks
• openai/codex source model-provider-info — confirmed wire_api = "responses" is the only accepted variant in 0.137.0; "chat" deserializes to CHAT_WIRE_API_REMOVED_ERROR