Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
CCS (Claude Code Switch) is a multi-provider profile and runtime manager designed to handle Claude Code, Codex, and other compatible CLIs without configuration conflict. The installation process establishes a local environment consisting of configuration files, shared directories for commands and skills, and optional Docker-based deployments. Sources: README.md:3-8, AGENTS.md:7-9
The setup logic is primarily driven by a post-installation script that ensures idempotency, cross-platform compatibility (Unix, macOS, Windows), and test isolation through environment variables like CCS_HOME. Sources: scripts/postinstall.js:10-18
Core Installation Methods
CCS supports three primary installation paths: Global NPM installation, Docker Compose, and native shell-based installation for specific CLI assets.
NPM Global Installation
The standard method for host installation involves NPM. Upon running npm install -g @kaitranntt/ccs, a post-install script automatically triggers to initialize the ~/.ccs/ directory and required configuration files. Sources: README.md:33-36, scripts/postinstall.js:10-12
Docker Deployment
For containerized environments, CCS provides a Docker Compose configuration. This initializes a dashboard on port 3000 and the CLIProxy on port 8317. Sources: README.md:21-27
Native CLI Asset Installation
Users can manually trigger the installation of CCS-specific commands and skills into the native Claude CLI environment using the --install flag. This copies assets like ccs.md and ccs-delegation skills into the ~/.claude/ directory. Sources: tests/native/unix/install.sh:91-105
Directory Structure and Initialization
The post-install script establishes a specific hierarchy in the user's home directory.
The diagram above illustrates the directory structure created during the setup process to isolate CCS configurations from standard Claude settings. Sources: scripts/postinstall.js:108-144
Key Directories Created
| Directory | Path (Default) | Purpose |
|---|---|---|
| CCS Home | ~/.ccs/ | Primary storage for CCS-specific configurations and shared assets. |
| Shared Root | ~/.ccs/shared/ | Centralized repository for commands, skills, agents, and plugins. |
| Completions | ~/.ccs/completions/ | Shell completion scripts (Bash, Zsh, Fish, PowerShell). |
| Claude Config | ~/.claude/ | Native Claude CLI settings directory initialized if missing. |
Sources: scripts/postinstall.js:108-144, 215-220, 238-241
Configuration Initialization Logic
The setup process prioritizes config.yaml as the primary configuration format (v6.x+). If a legacy config.json is detected, the system prepares for migration on the first run. Sources: tests/npm/postinstall.test.js:25-32, scripts/postinstall.js:160-175
Post-Install Execution Flow
The flow ensures that existing user configurations are never overwritten, maintaining idempotency across multiple runs. Sources: scripts/postinstall.js:108-284
Environment Variables
CCS uses specific environment variables to control installation behavior and directory resolution, which is critical for development and testing.
CCS_HOME: Redirects the base directory for all CCS operations (default:~). Used extensively in tests to avoid touching real user data. Sources: AGENTS.md:12-14, scripts/postinstall.js:25-27CLAUDE_CONFIG_DIR: Used for isolated account-based profiles. Sources: AGENTS.md:37-38NO_COLOR: Respected by the CLI to suppress ASCII color codes during setup and operation. Sources: AGENTS.md:21-22
Initializing CLIProxy and Profiles
During the initial setup, profiles for specific providers (e.g., Gemini, Codex) are not included by default. Instead, the installation creates an empty unified configuration.
- Empty Profiles:
config.yamlstarts with an emptyprofilesobject. Users populate this via presets or UI. Sources: tests/npm/postinstall.test.js:41-45 - CLIProxy Server: A default local server configuration is added to
config.yamlwith port8317andauto_start: true. Sources: scripts/postinstall.js:203-207 - On-Demand Creation: Profiles for OAuth providers like Gemini or Codex are added when the user first runs the respective command and completes authentication. Sources: scripts/postinstall.js:154-157
Verification and Validation
After the files are created, the installer performs a validation check to ensure:
- The
~/.ccs/directory exists. Sources: scripts/postinstall.js:68-71 - A valid
config.yamlorconfig.jsonis present. Sources: scripts/postinstall.js:74-80 - (Warning) If
~/.claude/settings.jsonis missing, the user is prompted to runclaude /login. Sources: scripts/postinstall.js:84-87
Users can manually verify the installation by running ccs doctor to check readiness or ccs --version to confirm binary functionality. Sources: README.md:126-128, tests/native/unix/install.sh:310-313
Summary
Installation and setup of CCS is an idempotent process that establishes a dual-directory environment (.ccs for management and .claude for native assets). Whether through NPM or Docker, the system ensures that user configurations are preserved while provisioning necessary shared directories for AI agents, skills, and commands. Sources: scripts/postinstall.js:10-18, README.md:21-27