Configuration Syncing
Relevant source files
The following files were used as context for generating this wiki page:
Configuration Syncing is a core system in CCS responsible for aligning local environment settings, Claude CLI components, and CLIProxy API profiles. Its primary purpose is to ensure that profile definitions, MCP servers, and Claude-specific extensions (commands and skills) are consistently available across different runtime environments without manual configuration thrash.
The system encompasses local YAML configuration management, symlink orchestration for Claude CLI resources, and automated migration logic to transition legacy JSON configurations into the unified YAML format.
Local Config Sync Architecture
The local configuration sync mechanism specifically handles the synchronization of CCS API profiles into the CLIProxy config.yaml. It utilizes a section-based replacement strategy to modify specific parts of the YAML file while preserving user comments and custom formatting.
Sync Logic and Data Flow
The sync process transforms internal ClaudeKey structures into the specific format required by the CLIProxy runtime. It performs an atomic write operation by creating a temporary file and renaming it upon success to prevent configuration corruption during failures.
Key Functions and Components
| Function | Purpose |
|---|---|
syncToLocalConfig() | Main entry point for syncing profiles to CLIProxy configuration. |
replaceSectionInYaml() | Internal logic to find and replace top-level YAML keys while preserving line structure. |
transformToConfigFormat() | Maps ClaudeKey fields (like api-key and base-url) to the CLIProxy schema. |
getLocalSyncStatus() | Retrieves metadata about the current config state, including key counts and path existence. |
Sources: src/cliproxy/sync/local-config-sync.ts:21-30, src/cliproxy/sync/local-config-sync.ts:108-110, src/cliproxy/sync/local-config-sync.ts:168-175
Claude CLI Component Syncing
The ccs sync command orchestrates the installation of delegation commands, skills, and MCP servers into the Claude CLI environment. This is achieved through a combination of directory installation and selective symlinking.
Symlink Management
The ClaudeSymlinkManager creates selective links from the CCS internal directory (~/.ccs/.claude/) to the user's active Claude directory (~/.claude/). This allows CCS to ship updated commands and skills that are immediately reflected in the Claude CLI.
Sync Command Execution Flow
The handleSyncCommand function executes the following sequence:
- Install Claude Directory: Copies core components to the CCS home.
- Symlink Orchestration: Links CCS items into the user's Claude environment.
- Shared Symlink Repair: Verifies symlinks in
~/.ccs/shared/to fix breaks caused by Claude CLI atomic writes. - MCP Server Syncing: Synchronizes MCP server definitions from global settings to all active non-bare profile instances.
Sources: src/commands/sync-command.ts:14-60
Configuration Migration
CCS includes a MigrationManager to transition users from legacy JSON-based configurations (v1) to the unified YAML format (v2). This process includes automated backups and deterministic profile renaming (e.g., kimi to km).
Migration Process Details
| Feature | Implementation |
|---|---|
| Backup | Creates a directory prefixed with backup-v1- containing all legacy JSON and settings files. |
| Profile Mapping | Maps profiles.json accounts and config.json variants into the new UnifiedConfig schema. |
| Rollback | Reverses the process by restoring files from the timestamped backup directory. |
| Persistence | Preserves references to *.settings.json files to maintain compatibility with the Claude CLI pattern. |
Sources: src/config/migration-manager.ts:51-60, src/config/migration-manager.ts:165-220, src/config/migration-manager.ts:260-280
Migration Sequence
REST API Integration
The cliproxy-sync-routes module exposes the configuration syncing functionality via a web interface, primarily for use by the CCS Dashboard.
- GET
/status: Provides visibility into whether the CLIProxy config exists and the number of syncable profiles. - GET
/preview: Performs a dry run, returning a masked payload of what the YAML section will contain. - POST
/: Triggers the actualsyncToLocalConfig()operation. - PUT
/auto-sync: Toggles theauto_syncconfiguration and restarts the file watcher.
Sources: src/web-server/routes/cliproxy-sync-routes.ts:22-35, src/web-server/routes/cliproxy-sync-routes.ts:69-80, src/web-server/routes/cliproxy-sync-routes.ts:121-135
Summary
Configuration Syncing in CCS provides a robust, fail-safe bridge between high-level profile management and low-level CLI runtimes. By combining atomic YAML updates, selective symlinking, and automated migration paths, the system ensures that user configurations remain portable, version-safe, and consistent across Claude Code and CLIProxy environments.