CC Desktop Switch points Claude Desktop at a different model provider

A local gateway that translates model names and keeps the key local

The core idea is a proxy that sits on the machine. Claude Desktop expects Claude-family model names, while the providers this tool supports use identifiers such as deepseek-v4-pro, kimi-k2.6, glm-5.1 or qwen3.6-plus. CC Desktop Switch keeps those real upstream model identifiers inside the local gateway and exposes Claude-safe route names to Claude Desktop. The purpose of the gateway, as the README puts it, is to keep model mapping, protocol compatibility, extra headers and upstream keys under local control. Since v1.0.18, Claude Desktop is configured to call the local gateway at 127.0.0.1, so the app has to keep running in the background whenever you use a third-party provider, and closing the window leaves it in the tray on Windows or hidden in the Dock app lifecycle on macOS. The audience is a desktop user of the official Claude client who wants to choose the backend, not a developer building an agent.

Unmapped routes are rejected rather than silently redirected

The most interesting design decision in the feature list is what happens when a model has no mapping. The README says the tool shows only explicitly mapped Claude-safe model routes in Claude Desktop, and that it rejects unmapped Claude model routes instead of silently falling back to an internal default. Since v1.0.19 only explicitly mapped Claude slots appear in the model menu, and Default remains an internal fallback that is not shown as a menu item. This is a deliberate refusal to be convenient. A silent fallback would let a request for one model quietly run on another, which is exactly the failure that produces confusing output and misattributed results, so the tool makes the gap visible instead. It also means the mapping is the configuration you have to maintain, and the DeepSeek 1M context and Max reasoning options in the screenshots are examples of the per-provider settings that live in that mapping.

Applying a provider means a full restart of Claude Desktop

The quick start is six steps, and one of them is the one people forget. You download and open the app, pick a provider preset or add a custom provider, enter your own API key, adjust model mappings if needed, click Apply to Claude Desktop, and then fully restart Claude Desktop. The troubleshooting section explains why that last step is not optional. Claude Desktop reads third-party inference configuration during startup, so closing only the chat window is often not enough, and the instruction is to fully quit and open it again. There is also a fallback local UI at http://127.0.0.1:18081 for when the desktop window cannot open, and the two default ports are the admin UI on 18081 and the local gateway on 18080.

Importing existing configurations, with OpenAI format left opt-in

The tool can import Anthropic-compatible CC-Switch configurations while leaving OpenAI-format entries opt-in, which is a careful choice given the name collision with the CLI-oriented tool the README contrasts itself against, farion1231/cc-switch. The README says this project is different from CLI-oriented tools of that kind because the goal here is to give regular desktop users a simple UI for provider setup, model mapping, health checks and local gateway compatibility. That framing explains the feature set: provider connectivity checks, model availability checks, SSE streaming, and custom upstream HTTP and SOCKS proxy support, all of which are things a person clicking through a UI wants to see working before they hand over a key. The import path is opt-in on the OpenAI side presumably because a protocol mismatch there produces failures that are much harder to diagnose than a missing mapping.

Running it from source, and the verification commands that come with it

The development section gives the whole loop, and it needs Python 3.11 or newer.

git clone https://github.com/lonr-6/cc-desktop-switch.git
cd cc-desktop-switch
pip install -r requirements.txt
python main.py

A browser based fallback is available for development.

python main.py --browser

And the verification step checks the Python side and the JavaScript side separately.

python -m compileall -q backend main.py tests
python -m unittest discover -s tests -v
node --check frontend/js/api.js
node --check frontend/js/app.js
node --check frontend/js/i18n.js

That last set is informative about the shape of the application. The backend, main.py and the tests are Python, and the frontend has JavaScript files for the API client, the app and the internationalization, checked with the node syntax checker. The requirements list confirms the stack: FastAPI and uvicorn for the local server, httpx with the socks extra for upstream calls, pywebview for the native window, pystray for the system tray, Pillow, pyinstaller for packaging, and on macOS only, the pyobjc bindings for Cocoa, Quartz, WebKit and Security. So it is a Python service with a webview shell, not an Electron app.

Uninstalling is the part that needs reading twice

The third troubleshooting entry is the one to look at before you install. CC Desktop Switch uses Claude Desktop's policy location for third-party inference settings, and a normal Windows uninstall now removes only policy values carrying the ccds_managed=true marker. Silent in-place upgrades pass /UPGRADE and keep the active provider configuration, while policies written under HKLM, delivered by MDM, or owned by another administrator are never removed. With v1.0.25 or earlier, the guidance is to use Clear Desktop configuration before uninstalling, and if Claude Desktop is still managed afterwards, to check for machine or organization level policy rather than deleting unrelated registry values. The symptom people hit is Claude Desktop showing Managed by your organization after uninstall. The design here is conservative, which is the right call for something that writes into another application's policy store, but it means the tool and Claude Desktop are coupled in a way that has to be understood before the first click.

Where this is the wrong shape of solution

The main limit is that it is a desktop application for one platform family. The README says the project is focused on Claude Desktop on Windows and macOS, so a Linux user has nothing here, and the macOS build is arm64 only in the asset list, with the Windows installer and a portable zip as the other options. The second limit is the one implied by the local gateway design. Because the key and the routing live on your machine and the app has to stay running, this is a single user setup, and it does not scale to a team or a server, where a proxy service would be the thing to build. The third is trust in the mapping. The tool decides which upstream model a Claude model name reaches, and while it refuses to guess, an incorrect mapping is still a silent wrong answer from the user's point of view, since the route looks like a normal model name in the menu. The last practical point is packaging. The README notes that Windows builds are not Authenticode-signed yet, so Windows may show an unknown publisher warning, which is mitigated by the release assets including .sha256, .sig and the public key for integrity checks.

Editorial conclusion

CC Desktop Switch suits a user of the official Claude Desktop client who has an Anthropic-compatible provider they want to use and does not want to hand their key to anyone, since the key and the model mapping stay on the machine and the gateway runs on localhost. It is the wrong tool if you are on Linux, because the project is focused on Claude Desktop on Windows and macOS, and it is the wrong tool if you want a hosted multi-user setup, because the whole design is a per-machine desktop app. Before installing, read the uninstall section carefully, because the tool writes into Claude Desktop's policy location and older versions required a manual clear step before removal. The last push was on 2026-08-18 and the current release is v1.0.26 from the same day.

Frequently asked questions

Official sources

1. License: MIT
2. lonr-6/cc-desktop-switch on GitHub
3. Project website
4. README
5. Releases