ccs/docs/codebase-summary.md

CCS Codebase Summary (v4.5.0)

Overview

CCS (Claude Code Switch) v4.5.0 is a lightweight CLI wrapper enabling instant profile switching between Claude Sonnet 4.5, GLM 4.6, GLMT (GLM with Thinking), and Kimi for Coding models. Version 4.x introduces AI-powered delegation, selective .claude/ directory symlinking, stream-JSON output, and enhanced shell completion. v4.5.0 completes transition to Node.js-first architecture with bootstrap-based installers.

Version Evolution

v4.5.0 Architecture (Current)

• Total LOC: ~8,477 lines (JavaScript only)
• Key Features: AI delegation, stream-JSON output, shell completion, doctor diagnostics, sync command
• New Components: delegation/, utils/claude-symlink-manager.js, utils/delegation-validator.js, utils/update-checker.js
• Architecture: Modular design with clear separation: auth/, delegation/, glmt/, management/, utils/
• Installation: Bootstrap-based native installers (requires Node.js 14+, no shell dependencies)

Evolution Summary

• v2.x: Vault-based credential encryption (~1,700 LOC)
• v3.0: Vault removal, login-per-profile (~1,100 LOC, 40% reduction)
• v4.0-4.4.x: Delegation system, .claude/ sharing, stream-JSON (~8,477 LOC including tests/utils)
• v4.5.0: Bootstrap-based installers, TypeScript npm package with quality gates

Core Components (v4.3.2)

1. Main Entry Point (bin/ccs.js - ~800 lines)

Role: Central orchestrator with delegation routing

Key Functions:

• execClaude(claudeCli, args, envVars): Unified spawn logic (Windows shell detection)
• handleVersionCommand(): Version display with delegation status
• handleHelpCommand(): Comprehensive help with delegation examples
• execClaudeWithProxy(claudeCli, profile, args): GLMT proxy lifecycle
• main(): Profile routing + delegation detection (-p flag)

v4.x Enhancements:

• Delegation detection: -p flag routes to DelegationHandler
• Stream-JSON output support for real-time tool tracking
• Shell completion installation (--shell-completion)
• Update checking and CCS sync commands
• Enhanced version display with API key validation

Architecture Flow:

// Delegation path (v4.0+)
if (args.includes('-p') || args.includes('--prompt')) {
  const { DelegationHandler } = require('./delegation/delegation-handler');
  const handler = new DelegationHandler();
  await handler.route(args);
}

// Settings profile (glm, kimi, glmt)
const expandedSettingsPath = getSettingsPath(profileInfo.name);
if (profileInfo.name === 'glmt') {
  await execClaudeWithProxy(claudeCli, 'glmt', remainingArgs);
} else {
  execClaude(claudeCli, ['--settings', expandedSettingsPath, ...remainingArgs]);
}

// Account profile (work, personal)
const instancePath = instanceMgr.ensureInstance(profileInfo.name);
registry.touchProfile(profileInfo.name);
const envVars = { CLAUDE_CONFIG_DIR: instancePath };
execClaude(claudeCli, remainingArgs, envVars);

2. Delegation System (bin/delegation/ - ~1,200 lines)

New in v4.0: Complete delegation subsystem

Components:

• delegation-handler.js (~300 lines): Routes -p commands, validates profiles
• headless-executor.js (~400 lines): Executes Claude CLI in headless mode with stream-JSON
• session-manager.js (~200 lines): Manages delegation session persistence (continue support)
• result-formatter.js (~150 lines): Formats execution results with cost/duration
• settings-parser.js (~150 lines): Parses profile settings for validation

Key Features:

• Stream-JSON output: Real-time tool visibility (--output-format stream-json --verbose)
• Session continuation: ccs glm:continue -p "follow-up" resumes last session
• Tool tracking: Shows file paths, commands, patterns as they execute
• Signal handling: Ctrl+C kills child processes properly
• Cost tracking: USD cost display per delegation
• 13 Claude Code tools supported: Bash, Read, Write, Edit, Glob, Grep, NotebookEdit, SlashCommand, TodoWrite, etc.

Delegation Flow:

User: ccs glm -p "add tests"
  ↓
DelegationHandler: Parse args, validate profile
  ↓
HeadlessExecutor: Spawn Claude CLI with --output-format stream-json --verbose
  ↓
Stream parser: Extract [Tool] lines, format in real-time
  ↓
SessionManager: Save session ID for :continue
  ↓
ResultFormatter: Display cost, duration, exit code

3. Auth System (bin/auth/ - ~800 lines)

Role: Multi-account management (unchanged from v3.0 core)

Components:

• auth-commands.js (~400 lines): CLI handlers for auth subcommands
• profile-detector.js (~150 lines): Profile type routing (settings vs account)
• profile-registry.js (~250 lines): Metadata management (profiles.json)

v4.x Status: Core logic stable, focus shifted to delegation

Profile Creation Flow (v3.0+):

# Create profile (prompts login)
ccs auth create work  # Opens Claude, auto-prompts OAuth
# Use directly (credentials in instance)
ccs work "task"

4. GLMT System (bin/glmt/ - ~900 lines)

Role: GLM with thinking mode via embedded proxy

Components (unchanged from v3.x):

• glmt-proxy.js (~400 lines): HTTP proxy on localhost:random
• glmt-transformer.js (~300 lines): Anthropic ↔ OpenAI format conversion
• reasoning-enforcer.js (~100 lines): Inject reasoning prompts
• locale-enforcer.js (~50 lines): Force English output
• delta-accumulator.js (~200 lines): Streaming state tracking
• sse-parser.js (~50 lines): SSE stream parser

Status: Stable experimental feature, not actively developed in v4.x

5. Management System (bin/management/ - ~600 lines)

Role: Diagnostics, recovery, instance management

Components:

• doctor.js (~250 lines): Health check diagnostics
• instance-manager.js (~220 lines): Instance lifecycle (v3.0 simplified)
• recovery-manager.js (~80 lines): Auto-recovery for missing configs
• shared-manager.js (~50 lines): Shared data symlinking (v3.1+)

v4.x Enhancements:

• doctor.js: Now checks delegation commands in ~/.ccs/.claude/commands/ccs/
• Validates .claude/ symlinks from v4.1

6. Utilities (bin/utils/ - ~1,500 lines)

New in v4.x: Expanded utility modules

Components:

• claude-detector.js (~70 lines): Claude CLI detection
• claude-dir-installer.js (~150 lines): Copy .claude/ from package (v4.1.1)
• claude-symlink-manager.js (~200 lines): Selective .claude/ symlinking (v4.1)
• config-manager.js (~80 lines): Settings config management
• delegation-validator.js (~100 lines): Validate delegation eligibility (v4.0)
• error-codes.js (~50 lines): Standard error codes
• error-manager.js (~200 lines): Error handling utilities
• helpers.js (~100 lines): TTY colors, path expansion
• progress-indicator.js (~150 lines): Spinner/progress display
• prompt.js (~100 lines): User input prompting
• shell-completion.js (~250 lines): Shell auto-completion installation (v4.1.4)
• update-checker.js (~100 lines): Version update notifications (v4.1)

Key Utilities:

• ClaudeDirInstaller: Copies .claude/ from npm package to ~/.ccs/.claude/
• ClaudeSymlinkManager: Creates selective symlinks to ~/.claude/ (Windows fallback to copy)
• DelegationValidator: Validates profile readiness (API keys, settings)

7. CCS .claude/ Directory (/.claude/ - packaged with npm)

New in v4.1: Selective symlink approach

Structure:

.claude/
├── commands/ccs/       # Delegation slash commands
│   ├── ccs.md          # /ccs "task" (auto-select profile)
│   └── ccs/continue.md # /ccs:continue "follow-up" (auto-detect profile)
├── skills/ccs-delegation/  # Auto-delegation skill
│   ├── SKILL.md        # Skill definition
│   ├── CLAUDE.md.template  # User CLAUDE.md snippet
│   └── references/troubleshooting.md
└── settings.local.json # Repomix permissions

Symlink Strategy (v4.1):

• Source: ~/.ccs/.claude/ (copied from npm package)
• Target: ~/.claude/commands/ccs@, ~/.claude/skills/ccs-delegation@
• Selective: Only CCS items symlinked, doesn't overwrite user's other commands/skills
• Windows: Falls back to copying if Developer Mode not enabled

Installation Flow (v4.1.1):

1. npm install -g @kaitranntt/ccs
2. Postinstall: ClaudeDirInstaller copies .claude/ → ~/.ccs/.claude/
3. Postinstall: ClaudeSymlinkManager creates selective symlinks → ~/.claude/
4. User can now use /ccs (auto-select) and /ccs:continue commands

File Structure (v4.3.2)

bin/
├── auth/               # Multi-account management (v3.0 core)
│   ├── auth-commands.js       # CLI handlers (~400 lines)
│   ├── profile-detector.js    # Profile routing (~150 lines)
│   └── profile-registry.js    # Metadata management (~250 lines)
├── delegation/         # AI delegation system (v4.0+)
│   ├── delegation-handler.js  # Route -p commands (~300 lines)
│   ├── headless-executor.js   # Execute with stream-JSON (~400 lines)
│   ├── session-manager.js     # Session persistence (~200 lines)
│   ├── result-formatter.js    # Format results (~150 lines)
│   ├── settings-parser.js     # Parse settings (~150 lines)
│   └── README.md              # Delegation documentation
├── glmt/               # GLM thinking mode (v3.x)
│   ├── glmt-proxy.js          # Embedded HTTP proxy (~400 lines)
│   ├── glmt-transformer.js    # Format conversion (~300 lines)
│   ├── reasoning-enforcer.js  # Reasoning prompts (~100 lines)
│   ├── locale-enforcer.js     # English enforcement (~50 lines)
│   ├── delta-accumulator.js   # Stream state (~200 lines)
│   └── sse-parser.js          # SSE parser (~50 lines)
├── management/         # System management (v3.x+)
│   ├── doctor.js              # Health diagnostics (~250 lines)
│   ├── instance-manager.js    # Instance lifecycle (~220 lines)
│   ├── recovery-manager.js    # Auto-recovery (~80 lines)
│   └── shared-manager.js      # Shared symlinking (~50 lines)
├── utils/              # Utilities (expanded in v4.x)
│   ├── claude-detector.js         # CLI detection (~70 lines)
│   ├── claude-dir-installer.js    # .claude/ installer (v4.1.1, ~150 lines)
│   ├── claude-symlink-manager.js  # Selective symlinks (v4.1, ~200 lines)
│   ├── config-manager.js          # Config management (~80 lines)
│   ├── delegation-validator.js    # Delegation validation (v4.0, ~100 lines)
│   ├── error-codes.js             # Error codes (~50 lines)
│   ├── error-manager.js           # Error handling (~200 lines)
│   ├── helpers.js                 # Utilities (~100 lines)
│   ├── progress-indicator.js      # Progress display (~150 lines)
│   ├── prompt.js                  # User prompting (~100 lines)
│   ├── shell-completion.js        # Shell completion (v4.1.4, ~250 lines)
│   └── update-checker.js          # Update checker (v4.1, ~100 lines)
└── ccs.js              # Main entry (~800 lines)

.claude/                # CCS-provided items (v4.1+)
├── commands/ccs/       # Delegation commands
│   ├── glm.md
│   ├── kimi.md
│   ├── glm/continue.md
│   └── kimi/continue.md
├── skills/ccs-delegation/  # Auto-delegation skill
│   ├── SKILL.md
│   ├── CLAUDE.md.template
│   └── references/troubleshooting.md
└── settings.local.json

scripts/
├── postinstall.js      # Auto-config + migration
├── sync-version.js     # Version management
├── check-executables.js # Validation
├── completion/         # Shell completions (v4.1.4)
│   ├── ccs.bash
│   ├── ccs.zsh
│   ├── ccs.fish
│   ├── ccs.ps1
│   └── README.md
└── worker.js           # Cloudflare Worker (ccs.kaitran.ca)

tests/
├── unit/               # Unit tests
│   ├── delegation/     # Delegation tests (v4.0+)
│   └── glmt/           # GLMT tests (v3.x)
├── npm/                # npm package tests
├── integration/        # Integration tests
└── shared/             # Shared test utilities

~/.ccs/                 # User installation
├── .claude/            # CCS items (copied from package)
│   ├── commands/ccs/
│   └── skills/ccs-delegation/
├── shared/             # Shared across profiles (v3.1+)
│   ├── commands@ → ~/.claude/commands/
│   ├── skills@ → ~/.claude/skills/
│   └── agents@ → ~/.claude/agents/
├── instances/          # Isolated Claude instances
│   └── work/
│       ├── commands@ → shared/commands/
│       ├── skills@ → shared/skills/
│       ├── agents@ → shared/agents/
│       ├── settings.json (if any)
│       ├── sessions/
│       └── ...
├── config.json         # Settings-based profiles
├── profiles.json       # Account-based profiles
├── delegation-sessions.json  # Delegation session history (v4.0)
├── glm.settings.json
├── glmt.settings.json
├── kimi.settings.json
└── logs/               # Debug logs

~/.claude/              # User's Claude directory
├── commands/ccs@ → ~/.ccs/.claude/commands/ccs/  # Selective symlink (v4.1)
├── skills/ccs-delegation@ → ~/.ccs/.claude/skills/ccs-delegation/  # Selective symlink
└── (user's other commands/skills remain untouched)

Data Flow (v4.3.2)

Delegation Execution (v4.0+)

User: ccs glm -p "add tests to UserService"
  ↓
ccs.js: Detect -p flag → route to DelegationHandler
  ↓
DelegationHandler: Parse { profile: 'glm', prompt: 'add tests', options: {} }
  ↓
DelegationValidator: Check API key, settings validity
  ↓
HeadlessExecutor: Spawn Claude CLI with:
  - --settings ~/.ccs/glm.settings.json
  - --output-format stream-json
  - --verbose
  - --prompt "add tests to UserService"
  ↓
Stream parser: Extract [Tool] lines in real-time
  - [Tool] Grep: searching for test patterns
  - [Tool] Read: reading UserService.js
  - [Tool] Write: creating UserService.test.js
  ↓
SessionManager: Save { sessionId, profile: 'glm', timestamp }
  ↓
ResultFormatter: Display summary
  - Working Directory: /home/user/project
  - Model: GLM-4.6
  - Duration: 12.3s
  - Cost: $0.0023
  - Session ID: abc123 (use :continue to resume)
  ↓
Exit with Claude CLI exit code

Settings Profile Execution (glm, kimi, glmt)

User: ccs glm "command"
  ↓
ccs.js: Parse arguments, detect profile "glm"
  ↓
ProfileDetector: detectProfileType("glm") → {type: 'settings'}
  ↓
ConfigManager: getSettingsPath("glm") → "~/.ccs/glm.settings.json"
  ↓
ccs.js: execClaude(["--settings", path, "command"])
  ↓
Claude CLI: Execute with GLM API

Account Profile Execution (work, personal)

User: ccs work "command"
  ↓
ccs.js: Parse arguments, detect profile "work"
  ↓
ProfileDetector: detectProfileType("work") → {type: 'account'}
  ↓
InstanceManager: ensureInstance("work") → "~/.ccs/instances/work/"
  ↓
ProfileRegistry: touchProfile("work") → Update last_used
  ↓
ccs.js: execClaude(["command"], {CLAUDE_CONFIG_DIR: instancePath})
  ↓
Claude CLI: Read credentials from instance, execute

Key Features (v4.3.2)

1. AI-Powered Delegation (v4.0)

• Headless execution: ccs glm -p "task" runs without interactive UI
• Stream-JSON output: Real-time tool visibility ([Tool] Write: file.js)
• Session continuation: ccs glm:continue -p "follow-up" resumes last session
• Cost tracking: USD cost display per delegation
• Signal handling: Proper Ctrl+C cleanup
• 13 tools supported: Comprehensive Claude Code tool coverage

2. Selective .claude/ Symlinking (v4.1)

• Package-provided: .claude/ ships with npm, copied to ~/.ccs/.claude/
• Selective symlinks: Only CCS items linked to ~/.claude/
• Non-invasive: Doesn't overwrite user's commands/skills
• Windows support: Falls back to copying if symlinks unavailable
• Auto-sync: ccs sync re-creates symlinks

3. Enhanced Shell Completion (v4.1.4)

• 4 shells: bash, zsh, fish, PowerShell
• Color-coded: Commands vs descriptions
• Categorized: Model profiles, account profiles, flags
• Auto-install: ccs --shell-completion or ccs -sc

4. Comprehensive Diagnostics (v4.1+)

• ccs doctor: Health check for installation, configs, symlinks, delegation
• ccs sync: Re-sync delegation commands and skills
• ccs update: Check for updates (v4.1+)

5. GLMT Thinking Mode (v3.x, stable experimental)

• Embedded proxy: HTTP proxy on localhost:random
• Format conversion: Anthropic ↔ OpenAI
• Reasoning injection: Force English, thinking prompts
• Debug logging: CCS_DEBUG_LOG=1 writes to ~/.ccs/logs/

Breaking Changes

v3.0 → v4.0

• No breaking changes: v4.0 purely additive (delegation features)
• New dependencies: None (all Node.js built-ins)
• Migration: Automatic via postinstall

v2.x → v3.0 (Historical)

• Command renamed: ccs auth save → ccs auth create
• Schema changed: Removed vault, subscription, email fields
• Migration required: Users must recreate profiles

Performance Characteristics (v4.3.2)

Delegation Performance

• Headless spawn: ~20-30ms overhead
• Stream parsing: <5ms per tool call
• Session save: ~10ms (JSON write)
• Total overhead: ~35-45ms vs direct Claude CLI

Profile Activation (unchanged from v3.0)

• Instance validation: ~5ms
• CLAUDE_CONFIG_DIR env var: ~1ms
• Claude CLI spawn: ~20-30ms
• Total overhead: ~26-36ms

.claude/ Symlinking (v4.1)

• Symlink creation: ~5-10ms per link
• Copy fallback (Windows): ~50-100ms total
• Sync command: ~100-200ms (full re-sync)

Security Model (v4.3.2)

Unchanged from v3.0

• No custom encryption (credentials managed by Claude CLI)
• Spawn with array arguments (no shell injection)
• Atomic file writes (temp + rename)
• Instance directory permissions (0700)

New in v4.x

• API key validation (checks for placeholder keys)
• Delegation eligibility checks (validates settings before execution)
• Signal handling (proper cleanup of child processes)

Testing Coverage (v4.3.2)

Unit Tests

• tests/unit/delegation/: Delegation system tests (v4.0+)
• tests/unit/glmt/: GLMT transformer tests (v3.x)
• tests/shared/unit/: Utility function tests

Integration Tests

• tests/npm/: End-to-end CLI functionality
• tests/integration/: Cross-platform behavior, edge cases

Test Count

• Total: ~50 test files
• Coverage: >90% for critical paths

Dependencies (v4.3.2)

Production

• cli-table3@^0.6.5: Table formatting (doctor command)
• ora@^5.4.1: Spinner display (progress indicators)

Development

• mocha@^11.7.5: Test runner

Note: Minimal dependencies, all critical functionality uses Node.js built-ins

Future Extensibility

Extension Points (v4.x)

1. New delegation profiles: Easy addition via DelegationValidator
2. Custom result formatters: Pluggable ResultFormatter
3. Session management: SQLite for better session queries
4. MCP integration: Delegation via MCP tools
5. Cost optimization: Model selection based on task complexity

Summary

CCS v4.3.2 Achievements:

• Delegation system: Complete AI-powered task routing with stream-JSON
• Selective symlinking: Non-invasive .claude/ directory sharing
• Shell completion: Enhanced UX with color-coded completions
• Diagnostics: Comprehensive health checking and auto-recovery
• Modular architecture: Clear separation of concerns (auth/, delegation/, glmt/, management/, utils/)

Design Principles Maintained:

• YAGNI: Only essential features implemented
• KISS: Simple, readable code without over-engineering
• DRY: Single source of truth for each concern

Code Quality:

• Total LOC: ~8,477 lines (bin/ JavaScript only)
• Test Coverage: >90% for critical paths
• Modularity: 7 subsystems (main, auth, delegation, glmt, management, utils, .claude/)
• Documentation: Comprehensive inline comments and external docs

v4.3.2 demonstrates successful feature expansion (delegation, symlinking, diagnostics) while maintaining core simplicity and zero breaking changes from v3.0. The modular architecture provides a sustainable foundation for future AI-powered development workflow enhancements.