tiennm99/ccs
1
0
Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-07-16 14:16:43 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
326e7592f26deabb227c1baaeb4e73afe50a7dbd
ccs/docs/project-overview-pdr.md
T
kaitranntt e45b46d207 docs: update documentation for modularization phases 6-9 
- mark settings, analytics, auth-monitor splits as complete
- add test infrastructure (99 tests, 90% threshold) to roadmap
- update codebase-summary.md with new modular structure
- add github issues backlog (13 issues categorized by priority)
- add future roadmap: multiple cliproxyapi, git worktree support
- update project-overview-pdr.md with v7.0 release items
- update system-architecture.md with new ui module structure
2025-12-21 03:45:02 -05:00

6.8 KiB
Raw Blame History

CCS Product Development Requirements (PDR)

Last Updated: 2025-12-21

Product Overview

Product Name: CCS (Claude Code Switch)

Tagline: The universal AI profile manager for Claude Code

Description: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, OpenRouter) with a React-based dashboard for configuration management.

Current Version: v7.x (OpenRouter integration added)

Problem Statement

Developers using Claude Code face these challenges:

  1. Single Account Limitation: Cannot run multiple Claude subscriptions simultaneously
  2. Provider Lock-in: Stuck with Anthropic's API, cannot use alternatives
  3. No Concurrent Sessions: Cannot work on different projects with different accounts
  4. Complex Configuration: Manual env var and config file management
  5. No Usage Analytics: Lack visibility into token usage and costs across providers

Solution

CCS provides:

  1. Multi-Account Claude: Isolated instances via CLAUDE_CONFIG_DIR
  2. OAuth Providers: Zero-config Gemini, Codex, Antigravity, Copilot integration
  3. API Profiles: GLM, Kimi, OpenRouter, any Anthropic-compatible API
  4. Visual Dashboard: React SPA for configuration management
  5. Automatic WebSearch: MCP fallback for third-party providers
  6. Usage Analytics: Token tracking, cost analysis, model breakdown

Target Users

User Type Use Case Primary Features
Individual Developer Work/personal separation Multi-account Claude
Agency/Contractor Client account isolation Profile switching
Cost-conscious Dev GLM for bulk operations API profiles, analytics
Enterprise Custom LLM integration OpenAI-compatible endpoints
Power User Multiple providers OpenRouter 300+ models

Functional Requirements

FR-001: Profile Switching

  • Switch between profiles with ccs <profile> command
  • Support default profile when no argument provided
  • Pass through all Claude CLI arguments

FR-002: Multi-Account Claude

  • Create isolated Claude instances
  • Maintain separate sessions, todolists, logs per account
  • Share commands, skills, agents across accounts

FR-003: OAuth Provider Integration

  • Support Gemini, Codex, Antigravity, Copilot OAuth flows
  • Browser-based authentication
  • Token caching and refresh

FR-004: API Profile Management

  • Configure custom API endpoints
  • Support Anthropic-compatible APIs
  • Model mapping and configuration
  • OpenRouter integration with 300+ models

FR-005: Dashboard UI

  • Visual profile management
  • Real-time health monitoring
  • Usage analytics with cost tracking
  • Modular page architecture (settings, analytics, auth-monitor)

FR-006: Health Diagnostics

  • Verify Claude CLI installation
  • Check config file integrity
  • Validate symlinks and permissions

FR-007: WebSearch Fallback

  • Auto-configure MCP web search for third-party profiles
  • Support Gemini CLI, OpenCode, Grok providers
  • Graceful fallback chain

Non-Functional Requirements

NFR-001: Performance

  • CLI startup < 100ms
  • Dashboard load < 2s
  • Minimal memory footprint

NFR-002: Reliability

  • Idempotent operations
  • Graceful error handling
  • Automatic recovery where possible

NFR-003: Security

  • Local-only proxy binding (127.0.0.1)
  • No credential exposure in logs
  • Secure token storage

NFR-004: Cross-Platform

  • Support Linux, macOS, Windows
  • Bash 3.2+, PowerShell 5.1+, Node.js 14+
  • Identical behavior across platforms

NFR-005: Maintainability

  • Files < 200 lines (with documented exceptions)
  • Domain-based organization
  • Barrel exports for clean imports
  • 90%+ test coverage

Technical Requirements

TR-001: Runtime Dependencies

  • Node.js 14+ or Bun 1.0+
  • Claude Code CLI installed
  • Internet access for OAuth/API calls

TR-002: Optional Dependencies

  • CLIProxyAPI binary (auto-managed)
  • Gemini CLI for WebSearch
  • Additional MCP servers

TR-003: Configuration

  • YAML-based config (~/.ccs/config.yaml)
  • JSON settings per profile
  • Environment variable overrides

Architecture Constraints

AC-001: CLI-First Design

  • All features accessible via CLI
  • Dashboard is convenience layer, not required
  • Scriptable and automatable

AC-002: Non-Invasive

  • Never modify ~/.claude/settings.json
  • Use environment variables for configuration
  • Reversible changes only

AC-003: Proxy Pattern

  • Use local proxy for provider routing
  • Claude CLI communicates with localhost
  • Proxy handles upstream API calls

Success Metrics

Metric Target Current
Startup time < 100ms Achieved
Dashboard load < 2s Achieved
Error rate < 1% Achieved
Test coverage > 90% 90% (497 tests)
File size compliance 100% < 200 lines 95%

Release Criteria

v1.0 Release (Complete)

  • Multi-account Claude support
  • OAuth provider integration (Gemini, Codex, AGY)
  • API profile management
  • Dashboard UI
  • Health diagnostics
  • WebSearch fallback
  • Cross-platform support

v7.0 Release (Complete)

  • OpenRouter integration with 300+ models
  • Interactive model picker
  • Dynamic model discovery
  • Tier mapping (opus/sonnet/haiku)
  • Settings page modularization (20 files)
  • Analytics page modularization (8 files)
  • Auth monitor modularization (8 files)
  • Comprehensive test infrastructure (497 tests)

v8.0 Release (Planned - Q1 2026)

  • Multiple CLIProxyAPI instances (load balancing, failover)
  • Native git worktree support
  • Critical bug fixes (#158, #155, #124)
  • Kiro auth support (#157)

v9.0 Release (Future - Q2 2026)

  • Team collaboration features
  • Cloud sync for profiles
  • Plugin system
  • CLI extension framework

Dependencies

External Services

  • Anthropic Claude API
  • Google Gemini API
  • GitHub Codex/Copilot API
  • Z.AI GLM API
  • OpenRouter API

Third-Party Libraries

  • Express.js (web server)
  • React (dashboard)
  • Vite (build tool)
  • shadcn/ui (UI components)
  • CLIProxyAPI (proxy binary)
  • Vitest (testing)

Risks and Mitigations

Risk Probability Impact Mitigation
Claude CLI API changes Medium High Version pinning, compatibility layer
Provider API deprecation Low High Fallback chain, multiple providers
OAuth token expiry Medium Medium Auto-refresh, clear error messages
Binary compatibility Low Medium Multi-platform builds, fallback

Related Documentation

Reference in New Issue View Git Blame Copy Permalink