Skip to main content

​
Architecture

CCS is designed with simplicity and reliability in mind. The architecture follows YAGNI, KISS, and DRY principles.

​
Core Components

Account Profiles

Isolated Claude instances with separate credentials and session data

OAuth Providers

CLIProxy-based providers (Gemini, Codex, Agy) with zero config

API Profiles

Settings-based profiles for GLM, KM, and custom providers

Profile Resolution

Smart profile detection that checks CLIProxy → Settings → Account profiles in order

Claude CLI Spawn

Spawns Claude CLI with resolved profile settings via --settings flag

​
Profile Mechanisms (Priority Order)

  1. CLIProxy hardcoded: gemini, codex, agy → OAuth-based, zero config
  2. CLIProxy variants: config.cliproxy section → user-defined providers
  3. Settings-based: config.profiles section → GLM, KM
  4. Account-based: Account metadata in config.yaml → isolated instances via CLAUDE_CONFIG_DIR

​
Execution Flow

1

Parse Arguments

Smart detection of profile vs CLI flags
2

Resolve Profile

Check CLIProxy → Settings → Account profiles
3

Configure Environment

Set env vars, CLAUDE_CONFIG_DIR if needed
4

Spawn Claude

Execute claude --settings <path> [args]

​
Directory Structure

~/.ccs/
├── config.yaml           # Main configuration (v8 unified format)
├── glm.settings.json     # GLM settings file
├── km.settings.json      # Kimi for Coding settings file
│
├── instances/            # Account profile instances
│   ├── work/
│   │   ├── .credentials.json
│   │   ├── session-env/
│   │   └── ...
│   └── personal/
│
├── cliproxy/             # OAuth provider data
│   └── auth/
│       ├── user@email-projectid.json      # gemini
│       ├── codex-user@email.json          # codex
│       └── antigravity-user_email.json    # antigravity
│
└── shared/               # Symlinked across profiles
    ├── commands/
    ├── skills/
    └── agents/

​
Design Principles

​
Non-Invasive

  • Never modifies ~/.claude/settings.json
  • Uses --settings flag for delegation
  • Claude CLI manages its own state

​
Idempotent

  • All install operations safe to run multiple times
  • Profile creation handles existing directories
  • No side effects on repeated runs

​
Cross-Platform Parity

  • Same behavior on macOS, Linux, Windows
  • Node.js handles platform differences
  • Unified codebase for all platforms

​
Configuration Priority Resolution

CCS resolves configuration in this order (highest to lowest priority):
  1. CLI flags - Direct command-line arguments (--proxy-host, --model, etc.)
  2. Environment variables - Shell exports (CCS_PROXY_HOST, ANTHROPIC_MODEL, etc.)
  3. config.yaml - User configuration file (~/.ccs/config.yaml)
  4. Built-in defaults - Hardcoded fallback values
This allows flexible overrides without modifying config files.

​
Proactive Token Refresh

OAuth providers (Gemini, Codex, Antigravity) proactively refresh tokens when they’re within 5 minutes of expiration. This prevents mid-session authentication failures and ensures seamless long-running conversations. How it works:
  • Token expiry checked before each API call
  • If token expires in <5 minutes, automatic refresh triggered
  • User never sees authentication interruptions
  • Works silently in background

​
Graceful Degradation

CCS implements fallback mechanisms for robust operation: Remote → Local Proxy Fallback:
  • Attempts remote CLIProxy connection first
  • On failure, automatically falls back to local proxy
  • Configurable via CCS_PROXY_FALLBACK_ENABLED or --remote-only flag
  • Health checks run with configurable timeout
Network Resilience:
  • Handles connection timeouts gracefully
  • Auto-retry on transient failures
  • Clear error messages when fallback exhausted

​
Technology Stack

ComponentTechnology
CLINode.js (ES modules)
BuildBun + TypeScript
DashboardReact + Vite
Packagenpm

​
Advanced Architecture Patterns

​
Unified Config Pattern

CCS v6+ uses a single config.yaml file for all configuration instead of scattered JSON files. This simplifies management and enables atomic updates. Benefits:
  • Single source of truth for all settings
  • Easier backup and version control
  • Atomic configuration updates
  • Reduced file I/O operations
Migration: Run ccs migrate to convert legacy config files to unified format.

​
Session Reference Counting

CLIProxy tracks active sessions using reference counting to prevent premature shutdown:
  • Each active Claude session increments counter
  • Session end decrements counter
  • Proxy only stops when counter reaches zero
  • Prevents disruption of concurrent sessions
Session Files:
  • ~/.ccs/cliproxy/sessions.json - Global session tracking
  • ~/.ccs/cliproxy/sessions-{port}.json - Variant-specific sessions

​
Version Mismatch Detection

CCS automatically detects CLIProxy binary version mismatches and handles them gracefully: Detection:
  • Compares expected version in config vs installed binary
  • Checks on every proxy startup
  • Validates on health check failures
Auto-Restart:
  • Stops outdated proxy instance
  • Downloads latest compatible version
  • Restarts proxy with new binary
  • Preserves session state
User Impact:
  • Transparent to user (no interruption)
  • Logged for debugging (~/.ccs/logs/)
  • Optional notification in dashboard

​
Performance

OperationTime
Profile switch< 10ms
First account activation~20-35ms
Subsequent activation~5-10ms
Dashboard startup~300ms