tiennm99/ccs
1
0
Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-07-17 02:16:43 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
3ec8703be0451925585feff648988ea4792bf382
ccs/docs/project-overview-pdr.md
T
kaitranntt 1ffd169b98 docs: add comprehensive documentation suite for modular architecture 
Add five documentation files reflecting Phase 5 UI modularization:
- codebase-summary.md: Complete directory structure for CLI and UI
- code-standards.md: 200-line file limit, barrel exports, naming conventions
- system-architecture.md: ASCII architecture diagrams and data flows
- project-roadmap.md: Completed phases 1-5, future work
- project-overview-pdr.md: Product development requirements
2025-12-19 20:17:55 -05:00

5.8 KiB
Raw Blame History

CCS Product Development Requirements (PDR)

Last Updated: 2025-12-19

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) with a React-based dashboard for configuration management.

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

Solution

CCS provides:

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

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
Enterprise Custom LLM integration OpenAI-compatible endpoints

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 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

FR-005: Dashboard UI

  • Visual profile management
  • Real-time health monitoring
  • Usage analytics

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, Brave, Tavily 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
  • Domain-based organization
  • Barrel exports for clean imports

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 TBD
Dashboard load < 2s TBD
Error rate < 1% TBD
Test coverage > 80% TBD
File size compliance 100% < 200 lines 85%

Release Criteria

v1.0 Release (Current)

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

v1.1 Release (Planned)

  • Settings page modularization
  • Enhanced analytics
  • Profile templates
  • Improved error messages

v2.0 Release (Future)

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

Dependencies

External Services

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

Third-Party Libraries

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

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