One Open Source Project a Day (No. 234): CC Switch — One App to Manage Providers, MCP, Skills, and Prompts Across Ten AI Coding Tools

Introduction

"Switch API providers in one click and manage MCP, Skills, and Prompts in one place — no more hand-editing JSON / TOML / YAML config files."

This is the 234th article in the "One Open Source Project a Day" series. Today's project is CC Switch.

Running multiple AI coding tools side by side is now the norm — Claude Code for one project, Codex for another, maybe switching over to Gemini CLI or Grok Build to compare outputs. The problem: each tool has its own configuration format. Claude Code uses one JSON structure, Codex uses TOML, Gemini CLI uses yet another YAML layout. Every time you switch providers, API keys, or models, you have to dig into that specific tool's config file and edit it by hand — and MCP servers and Skills need to be configured separately, per tool, with no sharing between them.

CC Switch turns this into a single unified desktop app: one tool to manage provider configuration across ten AI coding tools (Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi, MiniMax Code), with one-click switching, 90+ provider presets, and local request format-conversion routing (Routing) plus multi-provider model aggregation (Aggregation).

142.8k Stars, MIT License, built on Tauri 2 + Rust + React 18 — currently one of the largest open-source projects in this space.

What You Will Learn

• How CC Switch unifies configuration management across ten tools via Switch/Coexist modes
• The concrete differences and use cases of the three connection modes: Direct, Routing, Aggregation
• The "minimal intrusion" design philosophy: why switching providers won't destroy plugins or hooks you added by hand
• The local request routing's format-conversion and failover mechanism
• Data storage design: the ~/.cc-switch directory structure and cloud sync options

Prerequisites

• Experience using at least one AI coding CLI tool (Claude Code, Codex, Gemini CLI, etc.)
• Basic understanding of API providers, base URLs, and API keys
• Optional: familiarity with MCP (Model Context Protocol) basics will make the centralized-management section easier to follow

Project Background

What It Is

CC Switch's official positioning: "A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent." The fuller tagline reads: "The All-in-One Manager for Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes Agent, Pi & MiniMax Code." Its core value proposition: "Switch API providers in one click and manage MCP, Skills, and Prompts in one place — no more hand-editing JSON / TOML / YAML config files."

Team and Background

• Author: Jason Young (farion1231)
• License: MIT License
• Tech stack: Tauri 2, Rust, React 18, TypeScript, SQLite
• Official site: ccswitch.io

Project Stats

• ⭐ GitHub Stars: 142,800+
• 🍴 Forks: 9,500+
• 👀 Watchers: 264
• 📄 License: MIT

What It Does

The Problem It Solves

Managing multiple tools without CC Switch:
  Claude Code → JSON config, provider info buried in nested fields
  Codex       → TOML config, a completely different format
  Gemini CLI  → YAML config, yet another structure
  ↑ every provider/API-key/model switch means manually opening and
    editing each tool's own config file
  ↑ MCP servers, Skills, and Prompts have to be configured separately
    in each tool, with no sharing between them
 
CC Switch's approach:
  One desktop app, unified provider configuration across ten tools
  ↓ one-click switching, 90+ preset providers (AWS Bedrock, NVIDIA NIM,
    community relays, etc.)
  ↓ MCP, Skills, and Prompts configured once, reused across tools
  ↑ switching only touches the necessary connection fields
    (endpoint/key/model)
  ↑ plugins, hooks, and custom config remain untouched

Use Cases

1. Developers using multiple AI coding CLIs at once

   • Want unified provider and API key management instead of switching back and forth between each tool's own config file

2. Users who frequently switch between providers for comparison testing

   • Compare different models/providers' output quality with a one-click switch instead of manually editing config files

3. Teams wanting to reuse MCP server configuration across tools

   • Don't want to configure the same set of MCP servers separately in Claude Code, Codex, and Gemini CLI

4. Users who want to use GPT inside Claude Code, or mix models from different vendors

   • Use Routing mode for local format conversion to achieve cross-provider format compatibility

5. Users who need to track usage and cost across multiple providers

   • View token usage, spend, and subscription quotas directly on provider cards and in the system tray, without opening each vendor's own dashboard

Quick Start

Installation:

# macOS
brew install --cask cc-switch
 
# macOS upgrade
brew upgrade --cask cc-switch
 
# Arch Linux
paru -S cc-switch-bin

Basic usage flow:

1. Add a provider via a preset or custom config in the sidebar
2. Switch providers through the main UI, system tray, or project switcher
3. Effects vary by tool — Claude Code applies instantly, others may need a restart
4. Optionally enable the Routing/Aggregation tabs for cross-format conversion
   or multi-provider setups
5. Manage installed CLI tool versions via the "Apps" page

Core Features

1. Two Configuration Management Modes

2. Feature Support Matrix by Tool

3. Three Connection Modes

• Direct: the tool connects straight to the provider
• Routing: requests pass through CC Switch locally, with format conversion and failover, enabling cross-provider compatibility (e.g., GPT inside Claude Code)
• Aggregation: combines multiple providers' models into a single picker list, with each request routed to its model's actual provider

4. Centralized MCP, Skills, and Prompts Management

Configure once, reuse across tools — no need to set up the same MCP servers or Skills separately in each tool.

5. Session Reading View

Turns raw logs into a readable summary of steps/files/failures, so there's no need to dig through raw log files.

6. Usage and Quota Tracking

Token usage, spend, and subscription quotas are displayed directly on provider cards and in the system tray.

7. Data Storage Structure

Stored by default in ~/.cc-switch:

Supports WSL path configuration on Windows, and cloud sync via WebDAV or S3-compatible storage.

A Deeper Look

"Minimal Intrusion" Design: Switching Only Touches Necessary Fields

CC Switch has an explicit design principle worth examining: "even if you uninstall the app, your tools will continue to work normally." Switching providers only touches "key fields" (endpoint, key, model), while "plugins, hooks, MCP, and comments you added yourself" remain untouched.

If switching providers overwrote the whole config file:
  Hand-added hooks/plugins/comments → overwritten and lost
  ↑ every switch carries a risk of breaking existing configuration
  ↑ users become hesitant to switch freely, since the cost is unpredictable
 
CC Switch's "minimal intrusion" approach:
  Only touches connection fields — endpoint/key/model
  ↓ plugins, hooks, MCP, and custom comments are preserved as-is
  ↑ after uninstalling CC Switch, the tool's config file remains
    complete and usable
  ↑ users can switch freely and frequently without worrying about
    losing custom configuration

The significance of this design choice: it positions CC Switch as an "outer layer of configuration management," not "the single source of truth for config files." Even if you stop using CC Switch someday, the underlying tool's configuration remains complete and able to work independently — this lowers the psychological barrier to trying the tool, because the "exit cost" is explicitly engineered to be close to zero.

Routing Mode: Local Format Conversion Plus Failover

Routing mode's core capability is doing protocol format conversion locally — converting between Anthropic Messages, OpenAI Chat Completions, OpenAI Responses, and Gemini Native formats, enabling cross-vendor compatibility scenarios like "using GPT inside Claude Code."

Without Routing:
  Claude Code only understands the Anthropic Messages format
  ↑ a provider using an OpenAI-format API simply isn't usable
 
With Routing mode:
  Requests pass through local CC Switch first (default
  http://127.0.0.1:15721)
  ↓ format conversion: Anthropic ↔ OpenAI Chat Completions ↔ OpenAI
    Responses ↔ Gemini Native
  ↓ paired with circuit breaker and provider health monitoring for
    automatic failover
  ↓ a "Rectifier" feature automatically fixes requests some upstreams
    can't handle
  ↑ Claude Code doesn't need to know which provider is actually
    behind the scenes

This design turns "a tool only understands one API format" from a hard limitation into a problem a local proxy layer can solve — users don't need to wait for official vendor support for a given provider; as long as CC Switch supports the format conversion, cross-vendor combinations become feasible.

Aggregation Mode: Crediting Design Inspiration From opencodex

Worth noting: CC Switch's aggregation mode design explicitly credits inspiration from the open-source project opencodex. This is a commendable detail of open-source collaboration etiquette — rather than quietly absorbing a borrowed design idea, the documentation explicitly attributes it to the original author and contributors. Aggregation mode has one clearly stated capability boundary: "Aggregation doesn't provide failover" — a limitation the documentation states upfront, rather than letting users discover it the hard way. Additionally, Codex requires a full restart after model list changes to take effect, while Claude Code updates instantly — this kind of cross-tool behavioral difference is also explicitly documented.

Switch vs. Coexist: Two Modes Reflecting Real Tool Differences

CC Switch doesn't apply the same configuration management strategy to every tool — instead, it splits tools into Switch (single active provider) and Coexist (multiple providers coexisting) based on each tool's own capability boundaries. This split reflects a respect for each tool's native configuration mechanism: tools like Claude Code and Codex, which support explicitly switching an active provider, use Switch mode; while tools like OpenCode and Hermes, whose own configuration mechanism allows multiple providers to coexist in the config file simultaneously, are handled with Coexist mode instead of forcibly imposing a "only one can be active" model. This "adapt the management strategy to each tool's actual capability" design — rather than "force a single abstraction onto every scenario" — reflects genuine respect for underlying tool differences.

Its Stance on Headless/Server Scenarios

For GUI-less environments, CC Switch didn't build its own CLI version — instead, the documentation points to a separate community project, CC Switch CLI (SaladDay/cc-switch-cli), explicitly noting that it "shares the ~/.cc-switch data directory with the desktop app," but that "it's released separately, with potential version lag." This is a candid statement of ecosystem boundaries — it didn't force this capability into its own product scope, nor did it hide the real usage risk that "the two might not stay in version sync."

Project Links and Resources

Official Resources

• 🌟 GitHub: https://github.com/farion1231/cc-switch
• 🌐 Official Site: ccswitch.io
• 📄 License: MIT License
• 📝 Changelog: CHANGELOG.md in the repo

Related Resources

• opencodex — the source of design inspiration for CC Switch's aggregation mode
• CC Switch CLI — a community CLI version for headless/server environments, sharing the same data directory

Summary

Key Takeaways

1. One app unifies provider configuration across ten AI coding tools: ends the fragmented experience of hand-editing JSON/TOML/YAML
2. "Minimal intrusion" design keeps exit cost close to zero: switching only touches connection fields; plugins/hooks/custom config are preserved; the tool still works independently after uninstalling
3. Three connection modes cover different needs: Direct connection, Routing with local format conversion and failover, Aggregation combining multiple providers' models
4. Differentiated management strategy by tool capability: Switch (single active) / Coexist (multi-provider coexistence) each adapted to a given tool's own configuration mechanism
5. A candid sense of ecosystem boundaries: aggregation mode explicitly states "no failover," credits design inspiration from opencodex, points to an independent community CLI for headless scenarios instead of building one in-house

Who This Is For

• Developers using multiple AI coding CLIs simultaneously: want a single entry point to manage providers and configuration across all their tools
• Users who frequently switch providers for comparison: one-click switching is far more efficient than manually editing config files
• Users who want to mix models from different vendors: use Routing mode to achieve scenarios like "GPT inside Claude Code"
• Teams needing centralized MCP/Skills management: avoid duplicating the same capability set across every tool

One-Line Verdict

CC Switch isn't trying to answer "which AI coding tool is best" — it's solving the more mundane but very real pain point that using several tools shouldn't mean configuration management becomes its own burden.

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage