Introduction & Core Concepts
Relevant source files
The following files were used as context for generating this wiki page:
CCS (Claude Code Switch) is a Bun and TypeScript-based CLI and React dashboard designed for managing multiple provider profiles and runtimes for AI coding assistants. It serves as a unified command surface for Claude Code, Codex, Factory Droid, and other Anthropic-compatible APIs, allowing users to switch between different subscriptions, isolated account contexts, and local models without manual configuration changes.
The system is architected to provide "configuration parity" between the terminal and the dashboard, ensuring that core features are accessible via CLI while providing a visual management interface for complex workflows such as profile routing, analytics, and resource sharing.
Sources: README.md:3-8, CONTRIBUTING.md:3-5, AGENTS.md:5-7
System Architecture
CCS follows a hybrid architecture combining a high-performance CLI runtime with a localized web server and a React-based frontend. This structure allows for low-latency terminal execution while providing a rich UI for management tasks.
Core Components
| Component | Responsibility | Primary Paths |
|---|---|---|
| CLI Runtime | Main execution logic, command routing, and bootstrap wrappers. | src/, lib/ |
| Web Server | APIs for configuration management, diagnostics, and dashboard backend. | src/web-server/, src/api/ |
| Dashboard UI | React-based frontend for visual profile and resource management. | ui/src/ |
| Config Manager | Handles persistent settings, profile resolution, and directory isolation. | src/config/, src/utils/ |
Sources: CONTRIBUTING.md:10-18, AGENTS.md:16-21
High-Level Data Flow
The following diagram illustrates how a user request flows through the system, specifically focusing on the interaction between the CLI and the underlying configuration management.
The CLI acts as the primary entry point, routing commands to either the configuration manager for setting adjustments or to the CLIProxy/API bridge for model execution. The dashboard interacts with the same configuration logic via a local web server.
Sources: README.md:55-70, CONTRIBUTING.md:88-95, AGENTS.md:23-28
Configuration & Directory Structure
CCS isolates its operations to avoid interfering with native Claude or Codex installations. It primarily uses the ~/.ccs/ directory for its internal state, which can be overridden using the CCS_HOME environment variable for development and testing.
Directory Mapping
~/.ccs/: Root configuration directory.~/.ccs/shared/: Central storage for resources shared across profiles (commands, skills, agents, plugins).~/.ccs/config.yaml: The primary configuration file (version 2.0+).~/.ccs/profiles.json: Account-based profiles with isolatedCLAUDE_CONFIG_DIR.~/.ccs/completions/: Shell completion scripts.
Sources: CONTRIBUTING.md:120-128, scripts/postinstall.js:100-140, scripts/postinstall.js:235-245
Profile Resolution Priority
When launching a session, CCS resolves provider settings based on a specific hierarchy to ensure the correct credentials and base URLs are applied.
- Built-in CLIProxy Providers: Native support for Gemini, Codex, Antigravity.
- User-defined
config.cliproxy: Custom providers defined in the YAML config. - Settings-based
config.profiles: Individual profile overrides. - Account-based
profiles.json: Full isolation including unique config directories.
Sources: AGENTS.md:23-28, scripts/postinstall.js:160-175
Shared Resources Management
One of the core concepts of CCS is the ability to share logic and tools across different AI profiles through a symlink-based architecture.
Shared Resource Architecture
The SharedPage in the dashboard and the shared-routes in the web server manage five distinct types of shared resources:
- Commands: Markdown-based workflow steps.
- Skills: Logic extensions for the AI agents.
- Agents: Prompt-defined personas.
- Plugins: Registry-managed extensions.
- Settings: Shared
settings.jsonapplied across instances.
This architecture allows a single source of truth for custom prompts and tools while maintaining isolated execution environments for different profiles.
Sources: ui/src/pages/shared.tsx:32-40, tests/unit/codex-auth/codex-profile-resources.test.ts:31-40, scripts/postinstall.js:115-125
Codex & Compatibility Bridge
CCS provides a specific management layer for Codex, bridging it to Anthropic-compatible APIs. This is managed via the CodexPage and the codex-dashboard-service.
Diagnostics & Validation
The system performs deep diagnostics on the Codex environment, checking for:
- Binary installation and version (e.g.,
codex-cli 0.118.0). - Support for configuration overrides via the
-cflag. - Security of the configuration file (e.g., refusing to edit symlinked config files).
- Correctness of
model_providersentries and environment keys.
Sources: tests/unit/web-server/codex-dashboard-service.test.ts:160-180, ui/src/pages/codex.tsx:44-55
Structured vs. Raw Editing
The dashboard provides two modes for managing the Codex config.toml:
- Structured Controls: A UI-driven "Control Center" for managing model providers, project trust, and MCP servers.
- Raw Editor: A TOML editor for manual configuration.
The system prevents "config thrash" by disabling structured controls if the raw editor has unsaved changes or if the TOML is invalid, ensuring that the underlying file remains parsable.
Sources: ui/src/pages/codex.tsx:48-60, tests/unit/web-server/codex-dashboard-service.test.ts:250-265
Summary
The CCS project provides a robust layer of abstraction over AI coding assistant runtimes. By centralizing configuration in ~/.ccs/, providing a shared resource architecture via symlinks, and offering both CLI and Dashboard interfaces for environment diagnostics, it enables a developer-centric workflow that is both flexible and secure. Its core concepts—directory isolation, profile resolution hierarchy, and shared resource management—form the foundation for its multi-provider support.
Sources: README.md:12-25, CONTRIBUTING.md:210-220, AGENTS.md:75-80