cc-switch

Manages API provider credentials and configurations (OpenAI, Anthropic, Gemini, etc.) across five distinct CLI applications (Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw) through a SQLite-backed single source of truth. Uses application-specific serialization adapters to translate between the unified database schema and each tool's native config format (JSON, TOML, .env), automatically syncing changes bidirectionally without manual file editing.

Manages Model Context Protocol (MCP) server definitions and their bindings across Claude Code and OpenCode through a unified configuration system. Stores MCP presets (name, command, arguments, environment variables) in SQLite and synchronizes them to each application's MCP config file (JSON format), with validation against MCP schema and support for environment variable interpolation. Includes preset templates for common MCP servers and per-application enable/disable toggles.

Runs CC Switch as a background service accessible via system tray icon (Windows, macOS, Linux). Provides quick-access menu for common actions (switch provider, enable/disable MCP server, view session status) without opening the main window. Supports system tray notifications for events (provider health alerts, sync conflicts, session start/end). Implements auto-start on system boot and graceful shutdown.

Provides CLI commands (via cc-switch CLI or shell aliases) for common CC Switch operations (list providers, switch provider, enable/disable MCP server, view session status) that can be invoked from terminal or shell scripts. Implements IPC communication between CLI commands and the CC Switch background service to query/modify configuration. Supports shell completion (bash, zsh, fish) for CLI commands and arguments.

Implements full internationalization (i18n) support with translations for English, Japanese, and Chinese (Simplified and Traditional). Uses a JSON-based translation system with language detection based on system locale and manual language selection in settings. Supports right-to-left (RTL) languages and locale-specific formatting (dates, numbers, currency).

Implements automatic update checking and installation with staged rollout support. Checks for updates on startup and periodically (configurable interval), downloads updates in the background, and prompts user to install with option to defer. Supports rollback to previous version if update fails. Uses platform-specific update mechanisms (Windows: NSIS installer, macOS: DMG, Linux: AppImage or deb package).

Implements custom URL scheme (cc-switch://) for deep linking into specific CC Switch features and importing configurations. Supports deep links for adding providers (cc-switch://add-provider?type=openai&key=...), importing MCP servers (cc-switch://import-mcp?config=...), and importing skills (cc-switch://import-skill?url=...). Encodes configuration as base64-encoded JSON in URL parameters with validation and conflict resolution.

Manages custom skills (reusable prompt templates, tool definitions, or code snippets) through a single source of truth (SSOT) database with discovery from local filesystem and remote repositories. Supports skill installation via directory scanning or URL import, tracks skill metadata (name, version, author, dependencies), and synchronizes skill availability across all five CLI applications. Includes skill validation, versioning, and dependency resolution.

Manages system prompts and configuration templates for each CLI application through a unified editor and storage system. Stores prompts in SQLite with support for template variables (e.g., ${USER_NAME}, ${PROJECT_PATH}), syntax highlighting, and preview rendering. Synchronizes prompts to application-specific config files and supports per-application prompt overrides and inheritance chains.

Implements a local HTTP proxy service (running on localhost) that intercepts and routes API requests from CLI applications to configured providers with built-in failover and circuit breaker patterns. Routes requests based on provider configuration, implements exponential backoff retry logic, and tracks request latency and error rates for health monitoring. Supports request transformation (header injection, authentication wrapping) and response caching for common requests.

Tracks CLI application sessions (start time, end time, tool used, provider used) and API usage metrics (requests per provider, latency percentiles, error rates) in SQLite. Provides a session manager that records when each CLI tool is invoked and which provider was active, and a usage query system that aggregates metrics across time windows (hourly, daily, weekly). Supports session export and usage analytics dashboard.

Implements automated health checks for configured API providers by sending test requests (e.g., list models, get status) and measuring response latency and error rates. Stores health metrics in SQLite with timestamps and supports manual speed testing via UI button. Displays provider health status (up/down/degraded) with last-check timestamp and average latency. Integrates with circuit breaker to automatically mark unhealthy providers as unavailable.

Supports bulk import and export of CC Switch configuration (providers, MCP servers, skills, prompts, settings) via JSON or TOML files. Implements data migration logic to handle schema changes across CC Switch versions, with validation and conflict resolution (merge, overwrite, skip) when importing configurations that may conflict with existing data. Supports deep linking for configuration sharing (e.g., cc-switch://import?config=<base64-encoded-json>).

Monitors application config files (JSON, TOML, .env) for external changes and automatically syncs them back to the SQLite database, and vice versa. Uses file system watchers (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows) to detect changes with debouncing to avoid race conditions. Implements bidirectional sync with conflict detection (last-write-wins or user-prompted resolution) and maintains a sync log for debugging.

Supports optional cloud backup and synchronization of CC Switch configuration to a cloud service (e.g., GitHub, Dropbox, or custom server) with encryption and version control. Implements conflict resolution for multi-device scenarios (e.g., syncing between laptop and desktop) using timestamps and user-defined merge strategies. Supports selective sync (e.g., sync providers but not API keys) and offline mode with deferred sync.