CC Switch Tutorial: Safely Manage Claude Code, Codex, MCP, and Rollbacks

CC Switch, also often searched as CCSwitch or cc switch, is a desktop management tool for heavy users of AI programming. The problem it wants to solve is very direct: many people now use Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw at the same time, but each tool has its own configuration format, provider writing method, MCP configuration and Skills management method.

When you only use one tool, manually changing the configuration is bearable; once multiple tools are mixed, plus official accounts, third-party APIs, transfer services, local models, and team shared configurations, manually editing JSON, TOML, and .env will soon become a very annoying task.

The positioning of CC Switch is to integrate these scattered configurations into a cross-platform desktop application. What problem does it solve?

Modern AI programming tools are becoming more and more like “development colleagues in the command line”, but the ecology of each tool is not yet completely unified.

Common pain points include:

• The configuration formats of Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw are different.
• When switching API Providers, you need to repeatedly change the configuration file.
• MCP server is configured repeatedly across different tools.
• Prompt files such as CLAUDE.md, AGENTS.md, and GEMINI.md are difficult to maintain in a unified manner.
• Skills installation, synchronization, backup and uninstallation lack a centralized entrance.
• Multiple accounts, multiple relays, and multiple model service switching are easily confused.
• After the configuration file is manually modified and errors are made, the troubleshooting cost is very high.

The idea of ​​CC Switch is: don’t let users remember the configuration details of each tool, but use a unified interface to manage Provider, MCP, Prompts, Skills, Sessions and agents. What tools are supported?

The core support objects listed in the README include five categories:

• Claude Code
• Codex
• Gemini CLI
• OpenCode
• OpenClaw

These tools themselves have similar positioning, and they all revolve around AI programming, Agent workflow and command line collaboration. But their configuration systems are different, and the value of CC Switch lies in packaging these differences.

For people who often compare different AI programming tools, this is much less troublesome than manually flipping through configuration files every time. Provider Management

The first layer capability of CC Switch is Provider management.

It has more than 50 built-in Provider presets, and the directions mentioned in the README include AWS Bedrock, NVIDIA NIM, and various community relays. Users can copy the API key, import it with one click, and then switch in the interface.

There are several main practical points:

• Add Provider with one click.
• Provider drag and drop sorting.
• Quick switching of system tray.
• Provider import and export.
• Some general providers can be synchronized to multiple applications.

For many people, this feature is attractive enough. Because of the daily use of AI programming tools, it is often not “the model cannot be used”, but “which tool, which endpoint, and which account to use for this key today” that is easily confused. Local proxy and failover

In addition to writing configuration files, CC Switch also provides local proxy mode.

The focus of this capability is:

• Hot switching providers.
• Format conversion.
• Automatic failover.
• Fuse.
• Provider health check.
• Request correction.

To put it simply, it not only writes the configuration into the target tool, but also adds a layer of local proxy in the middle to allow different tools to access model services through the proxy.

This is useful for multi-provider users: if one service is down, it can be switched to another; if one model is expensive, it can be replaced with a cheaper one; if a certain request format is incompatible, it can also be adapted through the proxy layer. MCP, Prompts and Skills

CC Switch The more important second-level capability is the unified management of MCP, Prompts and Skills. MCP

It provides a unified MCP panel that can manage MCP servers between multiple applications, and supports two-way synchronization and Deep Link import.

This is very useful for users who are using MCP. Because there are many MCP servers, configurations can easily be scattered among different clients. The unified panel can reduce repeated configurations and facilitate migration. Prompts

The Prompts part supports Markdown editing, and corresponding files can be synchronized between different tools, for example:

• CLAUDE.md
• AGENTS.md
• GEMINI.md

These documents are essentially project specifications for the Agent. After unified management, it is easier to maintain team rules, project commitments and global reminders. Skills

Skills supports one-click installation from GitHub repositories or ZIP files, and also supports custom repository management, symbolic links, and file copying.

If you use tools such as Claude Code, Codex, and OpenClaw at the same time, Skills can easily become a bunch of files scattered in different directories. CC Switch Centralizing them can reduce maintenance costs. Sessions and workspaces

The README also mentions Session Manager and Workspace related capabilities.

It can browse, search and restore session history across multiple applications. For people who have used AI programming tools for a long time, session management is actually very important: a lot of valuable context, debugging processes, and solution comparisons are buried in old conversations.

In addition, it also provides a Workspace editor for OpenClaw, which can edit agent files such as AGENTS.md and SOUL.md with Markdown preview.

This shows that CC Switch is not just a “small tool for switching keys”, but is expanding towards the AI ​​Agent workbench. Cloud synchronization and data storage

CC Switch supports syncing Provider data via Dropbox, OneDrive, iCloud, NAS or WebDAV.

The local data storage method is also relatively clear:

• Database: ~/.cc-switch/cc-switch.db
• Local settings: ~/.cc-switch/settings.json
• Automatic backup: ~/.cc-switch/backups/
• Skills: ~/.cc-switch/skills/
• Skill backup: ~/.cc-switch/skill-backups/

It uses SQLite as the primary data source and emphasizes atomic writes and automatic backups, with the goal of avoiding configuration file corruption when switching or writing.

This design is critical for heavy users. Because once the configuration management tool itself writes a bad configuration, it will affect all AI programming tools. Installation method

CC Switch is a cross-platform desktop application built on Tauri 2.

The system requirements are roughly as follows:

• Windows: Windows 10 and above
• macOS: macOS 12 Monterey and above
• Linux: Ubuntu 22.04+, Debian 11+, Fedora 34+ and other mainstream distributions

Windows users can download the .msi installation package or portable version compressed package.

macOS users can use Homebrew:

1
2

brew tap farion1231/ccswitch
brew install --cask cc-switch

Update:

1

brew upgrade --cask cc-switch

Linux users can choose .deb, .rpm or AppImage. Arch Linux users can also install via paru -S cc-switch-bin.

As of May 6, 2026, the warehouse page shows that the latest release is CC Switch v3.14.1, and the release time is April 23, 2026. Technology stack

From the perspective of the warehouse structure, CC Switch is a typical Tauri desktop application:

• Front-end: React 18, TypeScript, Vite, TailwindCSS, TanStack Query, shadcn/ui
• Backend: Tauri 2, Rust, SQLite, Tokio
• Testing: Vitest, MSW, Testing Library

Core design patterns include:

• SQLite as Single Source of Truth.
• JSON saves device-level local settings.
• Write the live config of the target tool when switching.
• Backfill from live config when editing current Provider.
• Use temporary files plus rename to perform atomic writes.
• Database connection locking to avoid concurrent writing problems.

This type of architecture illustrates that projects are not simple scripts, but are designed as long-term desktop tools. Who is it suitable for?

CC Switch is suitable for the following types of users:

• Use Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw simultaneously.
• Frequently switch official accounts, third-party relays, local models or team providers.
• Massive use of MCP has begun.
• Want to maintain CLAUDE.md, AGENTS.md, GEMINI.md in a unified manner.
• Install, test and migrate Skills frequently.
• Want to see the session history and usage of different tools.

If you only use one AI programming tool, and always use the official login, and don’t bother with Provider, MCP and Skills, then its value may not be so obvious.

But if you have entered the state of “multi-tools, multiple accounts, multiple providers, and multiple projects”, it can save a lot of trivial configuration work. What to pay attention to

Such tools are convenient, but be aware of boundaries.

First, it will manage the configuration of multiple AI CLIs, so make sure you trust this tool and its writing logic.

Second, API key, relay endpoint, and MCP server are all sensitive configurations. Before turning on cloud synchronization, make sure that the synchronized directory and WebDAV service itself are safe and reliable.

Third, after switching Provider, most tools still need to restart the terminal or CLI to take effect. The README mentions that Claude Code supports hot switching for Provider data, but other tools usually still need to be restarted.

Fourth, when switching back to the official login, it is best to add the official provider according to the project description, and then go through the login process of the corresponding tool again. Check official channels before installation

The only official sources currently stated by the project are:

• Official website: ccswitch.io
• Source code: github.com/farion1231/cc-switch
• Download: Releases for this GitHub repository

CC Switch is free and open source software. Download sites that require recharge, ask for official account passwords, or use fake names should not be used. Windows downloads the MSI in Releases first; macOS can use:

After

1

brew install --cask cc-switch

is installed, check the installed version in “About” or the tool management interface. Do not download the fixed file based on the old version number in the third-party tutorial. Which files to back up before modification

The local data locations currently listed in the official CC Switch README are:

1
2
3
4
5

数据库：~/.cc-switch/cc-switch.db
设置：~/.cc-switch/settings.json
自动备份：~/.cc-switch/backups/
Skills：~/.cc-switch/skills/
Skill 备份：~/.cc-switch/skill-backups/

backups The default rotation keeps the last 10 copies, and the backup before Skills uninstallation keeps the last 20 copies. Automatic backup does not equal complete disaster recovery; before the first large-scale switch, you should exit CC Switch and copy the entire ~/.cc-switch directory to a controlled location.

At the same time, save the original configuration of the target tool separately, such as Codex config.toml in the user directory. Do not submit the backup containing the API Key to Git or upload it to a public network disk. A safe provider switch

1. Execute a minimal request in the original CLI and save the normal baseline.
2. Add a new Provider in CC Switch, which does not cover the only available official Provider.
3. Check the environment variables corresponding to the endpoint, model name and Key.
4. Exit completely after switching and restart the target CLI.
5. Test normal text first, then test streaming responses and tool calls.
6. When an exception occurs, switch back to the original Provider and confirm that the original CLI is restored.

Codex native custom Provider uses Responses protocol. The native proxy as of CC Switch 3.16 can convert Codex Responses requests into Chat Completions used by some third-party vendors and reconstruct streaming responses and tool calls. Whether it can work stably still depends on the specific version, upstream model and agent configuration. Just because the chat returns a sentence of text, it cannot be considered that all Codex workflows are compatible. Verification and fault location

After switching the Codex Provider, execute at least:

1
2

codex --version
codex --help

then completed three tests in a temporary Git repository:

• Read files and answer questions;
• Modify a test file and view the diff;
• Call a side-effect-free tool.

Common judgments:

CC Switch README Special Note: It defaults to the Codex directory in the application settings and will not automatically read CODEX_HOME. If a custom directory is used for the CLI, the same “Profile Directory” should be set in CC Switch. Rollback steps

1. Switch back to the previously reserved official or verified Provider in CC Switch.
2. Exit CC Switch and the target CLI.
3. Select backup before modification from ~/.cc-switch/backups/; do not overwrite the database if you are unsure.
4. Restore the separately saved config.toml if necessary.
5. Log in to the official Provider again and rerun the minimum baseline request.

The “minimally intrusive” design of CC Switch retains an active configuration, so the only currently active Provider cannot be deleted. The correct approach is to switch to an available Provider first and then clean up the misconfiguration. Security Boundary

• Do not use relays or paid mirror sites from unknown sources.
• Do not leak API Key in screenshots, logs and sync directories.
• Confirm server-side encryption, permissions, and data retention policies before syncing using WebDAV.
• Read the billing, data retention, and service terms of a third-party provider before using it.

- Do not subscribe to the OAuth reverse proxy using ChatGPT to circumvent the normal authorization path; the project release notes also note that this may violate the OpenAI Terms of Service. Summary

The value of CC Switch does not lie in the creation of another AI programming tool, but in its recognition of a reality: the AI programming ecosystem has entered a stage of coexistence of multiple tools.

Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw each have their own configuration systems, and MCP, Skills, Prompts, and Provider are expanding rapidly. Continuing to manually change configurations will sooner or later become a burden.

CC Switch collects these things into a desktop application, allowing users to switch providers, synchronize MCP, manage Skills, maintain prompt files and view sessions more easily. For heavy AI programming users, such tools are likely to move from “optional gadgets” to “everyday infrastructure.” FAQ

Are CC Switch and CCSwitch the same tool?

yes. When users search, they may write it as CC Switch, CCSwitch or cc switch. What is discussed here is the cross-platform desktop tool farion1231/cc-switch. What AI programming tools can CC Switch manage?

It is mainly oriented to AI CLI and Agent tools such as Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw, focusing on managing Providers, MCP, Prompts, Skills, agents, and sessions. Is CC Switch only used to switch API Key?

Not just. Switching Providers is its basic capability, but it is also expanding towards the AI ​​Agent workbench, including MCP management, Skills synchronization, prompt file maintenance, session viewing and cloud synchronization. When is it most worthwhile to install CC Switch?

If you use multiple sets of AI programming tools, multiple sets of API Providers, local models, relays or team shared configurations at the same time, CC Switch can significantly reduce the cost of manual configuration changes. References

• farion1231/cc-switch
• CC Switch Releases

Create an Ollama Local-Model Provider

Verify the Ollama service and exact model tag in the same user environment as CC Switch and Claude Code before editing configuration:

1
2

ollama list
Invoke-RestMethod -Uri 'http://127.0.0.1:11434/api/tags'

Create a provider such as Ollama Local, set its Base URL to http://127.0.0.1:11434/v1, choose the OpenAI-compatible / Chat Completions protocol, and copy the model tag exactly from ollama list. If the form requires an API key, use a non-secret local placeholder instead of a real cloud credential.

Back up the active provider before switching. In a read-only repository, test normal output, a file-reading tool call, and recovery after cancelling a request. A successful chat response alone does not prove that the full Claude Code agent workflow is compatible. Some local models have unreliable tool calling or emit a format that Claude Code does not expect; change the model, use CC Switch protocol conversion where applicable, or roll back immediately.

If the CLI works but the API does not, check whether Ollama is running on the other side of the Windows/WSL boundary, whether port 11434 is listening, and whether the firewall blocks it. If the endpoint lists models but the client reports “model not found,” the configured tag is usually incomplete. Never expose an unauthenticated Ollama port directly to the Internet.