Architecture & Component Layout
Relevant source files
The following files were used as context for generating this wiki page:
CCS (Claude Code Switch) is a TypeScript/Bun-based CLI and dashboard designed to manage multi-provider profiles and runtimes for Claude Code, Codex, and other compatible LLM interfaces. The system provides a unified command surface and a web-based management interface to eliminate configuration friction when switching between local models, various Claude subscriptions, and OpenAI-compatible APIs.
Sources: README.md:1-12, AGENTS.md:7-9
Core System Architecture
The project is structured into three primary layers: the CLI runtime, the web-based dashboard, and the local proxy services. Execution remains CLI-first, with the dashboard providing a visual configuration and monitoring layer that maintains parity with CLI capabilities.
Project Structure
The repository follows a clear separation of concerns:
- src/: Contains the TypeScript source for the CLI and the web server.
- ui/: A React-based dashboard for visual configuration.
- lib/: Bootstrap wrappers and prompt templates.
- docker/: Containerization support for deploying the dashboard and CLIProxy.
Sources: AGENTS.md:17-23, CONTRIBUTING.md:14-22
System Components Flow
The following diagram illustrates how the CLI, Dashboard, and external providers interact through the CCS Unified Config and CLIProxy.
Sources: README.md:38-48, AGENTS.md:25-30
Configuration & Profile Management
CCS uses a Unified Configuration strategy, primarily serialized as YAML, to manage diverse account types and provider settings.
Profile Resolution Priority
When a command is executed, CCS resolves the target profile using the following priority:
- Built-in CLIProxy providers: Gemini, Codex, Antigravity.
- User-defined providers: Configured in
config.cliproxy. - Settings-based profiles: Configured in
config.profiles. - Account-based profiles: Defined in
profiles.jsonwith isolatedCLAUDE_CONFIG_DIR.
Sources: AGENTS.md:25-30
Configuration Schema
The config.yaml file is organized into distinct functional sections.
| Section | Description |
|---|---|
| Accounts | Isolated Claude instances with separate auth/sessions. |
| Profiles | API-based providers (GLM, Kimi, etc.) pointing to .settings.json files. |
| CLIProxy | OAuth-based providers (Gemini, Codex, etc.). |
| Proxy Routing | OpenAI-compatible local proxy selection rules. |
| WebSearch | Local search backends (Exa, Tavily, Brave) for third-party profiles. |
| Continuity | Artifact reuse across execution profiles. |
Sources: src/config/loader/yaml-serializer.ts:33-160
Dashboard Design System
The dashboard is built using a strict design system defined by "archetypes" to ensure layout consistency.
Layout Archetypes
The UI uses three primary identity-strip patterns and two body archetypes:
- HeroBar: A single-row dense strip containing the logo, title, and up to four hero metrics. Used for the home page.
- Config Archetype: A strict three-pane layout (Rail-anchored identity) where the left rail contains page identity and entity lists, the center contains forms, and the right contains raw JSON/TOML data.
- Monitor Archetype: Used for data visualization, featuring a KPI row and a grid of cards for metrics.
Sources: ui/src/pages/_styleguide.tsx:102-120, ui/src/pages/_styleguide.tsx:135-165
Config Layout Structure
Config pages are designed as a strict two-column shell where columns are flush against the global topbar.
Sources: ui/src/pages/_styleguide.tsx:139-145
Resource & Shared Services
CCS facilitates the sharing of skills, agents, and commands across different Claude profiles.
Shared Resource Types
Shared resources are stored under ~/.ccs/shared/ and are typically symlinked into profile-specific directories.
- Commands: Markdown files defining custom CLI workflows.
- Skills: Skill definitions found in
SKILL.mdwithin subdirectories. - Agents: Custom agent prompts stored in
.mdor.tomlformats. - Plugins: Installed Claude plugins managed via a shared registry (
installed_plugins.json).
Sources: ui/src/pages/shared.tsx:50-70, tests/unit/web-server/shared-routes.test.ts:133-250
Resource Policies
The system distinguishes between Shared Accounts (using the global resource pool) and Profile-Local Accounts (using isolated resources).
Sources: ui/src/pages/shared.tsx:443-465
Conclusion
The CCS architecture centralizes the complexity of managing multiple AI providers into a unified CLI and Dashboard interface. By utilizing a shared configuration layer and a structured local proxy (CLIProxy), it allows developers to switch between disparate models and runtimes while maintaining session continuity and tool availability.
Sources: README.md:31-36, CONTRIBUTING.md:200-210