How lonr-6/cc-desktop-switch works
1. Product shape
CC Desktop Switch is a local desktop companion app for Claude Desktop, not a cloud service. It runs as a Python backend with a browser-based UI and acts as a local control plane for third-party, Anthropic-compatible providers.
2. Two main runtimes
The repo is split into:
- a Python backend that exposes local APIs and the gateway behavior
- a static frontend in HTML/CSS/vanilla JS for the admin UI
The README indicates the app can run as a normal desktop window or as a browser fallback at http://127.0.0.1:18081.
3. Core architectural role of the backend
The backend is the system of record for provider settings, model mappings, proxy settings, and Claude Desktop integration. The key modules suggest clear boundaries:
- config.py for persisted settings
- registry.py for provider/model registration
- provider_tools.py and api_adapters.py for provider-specific API behavior
- proxy.py for upstream proxy handling
- model_alias.py for mapping provider model IDs to Claude-safe names
- ccswitch_import.py for importing CC-Switch-style configs
- update.py for release/update support
- i18n.py for localized UI strings
4. Local gateway boundary
A major design choice is the local gateway on 127.0.0.1:18080. Claude Desktop is configured to talk to this local layer rather than directly to every third-party provider. That gateway is responsible for:
- translating Claude Desktop requests into provider-specific requests
- preserving upstream API keys and headers locally
- enforcing model routing and rejecting unmapped routes instead of silently falling back
5. Provider management flow
The user selects or creates a provider preset in the UI, enters credentials, and the backend stores the configuration locally. The provider abstraction appears to support:
- preset providers such as DeepSeek, Kimi, Zhipu GLM, Alibaba Cloud Bailian, Xiaomi MiMo
- custom Anthropic-compatible endpoints
- optional OpenAI-format imports, but only if the user opts in
This indicates the architecture is built around provider adapters + configuration registry, not hardcoded single-provider logic.
6. Model mapping and routing
The repo emphasizes model aliasing as a separate concern from provider connectivity. Third-party model IDs remain internal to the gateway, while Claude Desktop only sees Claude-safe slots. This is important because the model menu in Claude Desktop is intentionally filtered to only explicitly mapped routes, preventing accidental exposure of unsupported models.
7. Connectivity, health, and streaming
The backend includes support for:
- provider connectivity checks
- model availability checks
- SSE streaming
- custom HTTP/SOCKS upstream proxying
These features suggest the gateway is not just a config writer; it also validates and proxies live traffic so Claude Desktop can interact with provider APIs reliably.
8. Claude Desktop integration boundary
The app’s “Apply to Claude Desktop” action likely writes or updates Claude Desktop’s third-party configuration on the local machine. The project is explicitly focused on Windows and macOS, so the backend must bridge between:
- local app state in ~/.cc-desktop-switch/config.json
- platform-specific Claude Desktop configuration locations
- restart/relaunch behavior required for Claude Desktop to pick up changes
9. Frontend structure
The frontend is a lightweight single-page admin UI built from:
- frontend/index.html
- frontend/css/style.css
- frontend/js/app.js
- frontend/js/api.js
- frontend/js/i18n.js
- frontend/assets/providers
This points to a UI that is mostly a thin client over backend APIs, with provider-specific assets and localized text bundled locally.
10. Startup and process lifecycle
The root main.py and backend/main.py suggest a launcher/orchestrator layer. The README also mentions:
- duplicate-instance prevention on Windows
- tray behavior on Windows
- hidden/background lifecycle on macOS
So the app is designed as a long-running local utility, not a one-shot configuration tool, because Claude Desktop depends on the gateway staying alive.
11. Packaging and platform-specific delivery
The repo contains substantial packaging infrastructure:
- Windows: build.spec, installer.nsi, start.bat, build.bat
- macOS: macos/ build scripts, entitlements, pkg/dmg creation
- release automation: .github/workflows/release.yml, scripts/
This means the repository is architected for desktop distribution artifacts, not just source execution.
12. Validation and quality gates
The tests/ directory covers macOS config/library behavior and provider config/proxy behavior, which matches the app’s two riskiest areas: platform integration and network routing. The README’s verification steps also show a split between Python compilation/tests and JS syntax checks, reflecting the backend/frontend boundary.
13. External dependencies that matter
Material dependencies include FastAPI, httpx, and uvicorn on the backend, and Bootstrap 5.3 via CDN on the frontend. These are not incidental: FastAPI and uvicorn define the local API/server surface, while httpx underpins outbound provider calls and streaming through the gateway.
14. Overall architecture in one sentence
The repo is a local desktop orchestration app that stores provider configuration, maps models, proxies requests through a localhost gateway, and applies the resulting setup to Claude Desktop across Windows and macOS.
Main entry points: main.py Server · release.yml Release flow · app.js UI logic · index.html Admin UI
Components 22
Backend
Local Python control plane, gateway, and integration logic.
- Server · Backend application entrypoint and local API host.
backend/main.py - Settings · Persists local app configuration and provider settings.
backend/config.py - Registry · Tracks provider presets, models, and available routes.
backend/registry.py - Adapters · Provider-specific request translation and API shaping.
backend/api_adapters.py - Provider tools · Connectivity checks, model checks, and provider helper logic.
backend/provider_tools.py - Proxy · Handles HTTP/SOCKS proxying for outbound provider traffic.
backend/proxy.py - Model alias · Maps provider model IDs to Claude-safe model names.
backend/model_alias.py - Config import · Imports CC-Switch style provider and model configuration.
backend/ccswitch_import.py - Updater · Update and release metadata handling.
backend/update.py - Backend i18n · Localized strings used by the backend and UI integration.
backend/i18n.py
Frontend
Static browser UI for local administration.
- Admin UI · Main browser-based administration shell.
frontend/index.html - UI logic · Frontend state management and screen behavior.
frontend/js/app.js - UI API · Browser-side wrapper for local backend calls.
frontend/js/api.js - UI i18n · Frontend string localization and language selection.
frontend/js/i18n.js - Styles · Visual styling for the local admin interface.
frontend/css/style.css
Platform
Claude Desktop integration and OS-specific lifecycle.
- Launcher · Starts the desktop app and coordinates the runtime.
main.py - Claude Desktop · Local desktop app that consumes the gateway and config.
- Claude config · Platform-specific Claude Desktop configuration files and app state.
Delivery
Packaging, release, and distribution artifacts.
- Release flow · Build and release automation for desktop distribution.
.github/workflows/release.yml - Windows package · Windows build and installer artifacts.
installer.nsi - macOS package · macOS build scripts, entitlements, and package creation.
macos/build-macos.sh - Tests · Coverage for platform integration, provider config, and proxy behavior.
tests/test_provider_config_and_proxy.py
Connections 24
- Launcher → Server: starts · Launcher hands off to the local server/runtime.
- Server → Settings: loads · Reads and persists local settings.
- Server → Registry: uses · Initializes provider and model registry state.
- Server → Adapters: routes via · Dispatches provider-specific request handling.
- Server → Proxy: proxies through · Applies upstream proxy settings for outbound traffic.
- Server → Model alias: maps · Translates provider models into Claude-safe aliases.
- Server → Provider tools: checks · Runs connectivity and availability validation.
- Server → Config import: imports · Supports external config import workflows.
- Server → Updater: updates · Surfaces update and release support.
- Server → Backend i18n: localizes · Provides localized backend-facing strings.
- Admin UI → UI logic: loads · Browser shell hosts the UI logic.
- UI logic → UI API: calls · Frontend invokes local backend endpoints.
- UI logic → UI i18n: uses · UI text and language switching.
- Admin UI → Styles: styles · Applies local styling to the admin UI.
- UI logic → Server: administers · UI controls the local backend control plane.
- Server → Claude config: writes · Applies Claude Desktop configuration changes.
- Claude config → Claude Desktop: enables · Claude Desktop consumes the local gateway setup.
- Server → Claude Desktop: serves · Provides the localhost gateway Claude Desktop talks to.
- Release flow → Windows package: builds · Release automation produces Windows artifacts.
- Release flow → macOS package: builds · Release automation produces macOS artifacts.
- Release flow → Server: packages · Bundles the backend runtime into releases.
- Release flow → Admin UI: packages · Bundles the static frontend into releases.
- Tests → Server: validates · Tests backend integration and proxy behavior.
- Tests → Claude config: validates · Tests macOS configuration/library behavior.