ccs/docs/project-overview-pdr.md

CCS Product Development Requirements

Product Overview

Product name: CCS (Claude Codex Switch)

Purpose: Provide one profile and runtime-management surface for Claude Code, Codex CLI, Factory Droid, CLIProxy-backed OAuth providers, and compatible API profiles.

CCS includes:

• a TypeScript CLI and local server;
• a React dashboard for configuration, account, health, and usage workflows;
• isolated account contexts and per-profile settings;
• local or remote CLIProxy routing;
• optional managed tools such as WebSearch and image analysis; and
• an integrated Docker image containing CCS, CLIProxy, and the dashboard.

Release versions and completed-release inventories belong in CHANGELOG.md, not this evergreen requirements document.

Problem

Developers need to switch between accounts, providers, and compatible CLIs without repeatedly editing credentials or allowing one session's configuration to leak into another. They also need a visible, reversible way to manage local proxy state and diagnose provider readiness.

Product Principles

1. CLI first: Core configuration and launch behavior remains scriptable.
2. Explicit state: Users can inspect which profile, provider, target, and proxy mode CCS selected.
3. Isolation: Account sessions use separate configuration roots where the target supports them.
4. Compatibility: CCS adapts provider credentials to a target without redefining the provider or target protocol.
5. Reversibility: Persistent writes are explicit and recoverable.
6. Local ownership: Credentials and profile state remain on infrastructure selected by the user.

Users

User	Primary need
Individual developer	Separate accounts, projects, and provider profiles
Consultant or agency	Isolate client contexts
API consumer	Reuse Anthropic-compatible and OpenAI-compatible providers
Power user	Manage OAuth accounts, routing, health, and quota state
Team operator	Run a shared remote CLIProxy or integrated Docker service

Functional Requirements

FR-001: Profile resolution and launch

• Launch the default profile with ccs.
• Launch named settings, account, and CLIProxy profiles.
• Pass target-specific arguments without losing CCS-owned routing constraints.
• Resolve provider and target aliases through canonical registries.

FR-002: Account isolation

• Maintain an account registry.
• Use isolated CLAUDE_CONFIG_DIR roots for Claude account profiles.
• Keep shared resources and instance-owned state distinguishable.
• Prevent one account's provider overrides from leaking into another launch.

FR-003: Provider integration

• Support API-key profiles and OAuth-backed CLIProxy providers.
• Support local and remote CLIProxy operation.
• Keep original and Plus CLIProxy backends explicit; do not silently substitute one when a requested provider requires the other.
• Treat provider capability metadata as code-owned, not prose-owned. See src/cliproxy/provider-capabilities.ts and src/cliproxy/types/provider-types.ts.

FR-004: Target adapters

• Support Claude Code, Factory Droid, and Codex CLI through target adapters.
• Deliver credentials in the form owned by each target: environment variables for Claude launches, managed custom-model state for Droid, and transient configuration overrides for CCS-routed Codex launches.
• Preserve user-owned target configuration outside the explicitly managed fields.

FR-005: Configuration management

• Store CCS configuration under the directory resolved by getCcsDir().
• Store API profile launch settings in <profile>.settings.json files under that directory.
• Require all environment values written to settings files to be strings.
• Keep shared Claude settings unchanged during normal profile launches.
• Allow the explicit ccs persist workflow to merge a profile into ~/.claude/settings.json; back up the existing file and write atomically.
• Reject unsafe settings-file targets such as symlinks.

FR-006: Dashboard and diagnostics

• Provide local APIs and a React UI for supported configuration workflows.
• Surface health, authentication, provider, routing, and usage state without exposing credentials.
• Keep dashboard changes aligned with the same configuration contracts used by the CLI.

FR-007: Managed tools

• Provide WebSearch and image-analysis integration for profiles that need CCS-managed alternatives.
• Prefer explicit provider routes.
• Fail closed when enabled third-party WebSearch cannot prepare its constrained MCP replacement.
• Allow image analysis to use compatible native behavior when its managed route is unavailable.

FR-008: Remote proxy

• Resolve remote proxy settings from supported CLI flags, environment variables, and CCS configuration.
• Verify reachability before use.
• Fall back to a local proxy only when fallback is enabled.
• Fail instead of falling back when remote-only mode is selected.

FR-009: Quota and account-pool management

• Display supported quota and account health data.
• Let users pause and resume accounts.
• Keep routing-strategy changes explicit.
• Temporarily remove exhausted accounts from rotation only under the CCS-managed cooldown contract and restore only CCS-created pauses.

FR-010: Docker deployment

• Publish an integrated multi-architecture image containing CCS, CLIProxy, and the dashboard.
• Persist CCS state and service logs in declared volumes.
• Expose dashboard and CLIProxy service ports.
• Health-check both services.
• Do not bundle target AI CLIs into the integrated image; consumers that need them run sibling containers or install them separately.

FR-011: Shell and editor integration

• Export shell-safe environment values through ccs env.
• Support the documented shell output formats.
• Keep persistent shared settings behind ccs persist.
• Keep editor-specific writes scoped to the selected editor and user layer.

Non-Functional Requirements

NFR-001: Security

• Do not print or log credentials.
• Bind local proxy services to loopback unless the user explicitly selects a deployment that exposes them.
• Validate file types and use safe replacement semantics for managed sensitive configuration.
• Keep remote transport and authentication choices explicit.

NFR-002: Reliability

• Make setup and repair operations idempotent where practical.
• Preserve existing user state when merging managed configuration.
• Report recovery actions in actionable error messages.
• Clean up child processes and temporary runtime state on exit.

NFR-003: Portability

• Support macOS, Linux, and Windows for the host CLI where target dependencies allow.
• Support Node.js 18 or newer, as declared by package.json.
• Support Bun 1.0 or newer for development and supported runtime workflows.
• Keep terminal output ASCII-only and respect NO_COLOR and TTY detection.

NFR-004: Maintainability

• Keep provider metadata centralized.
• Use target adapters instead of target checks scattered through dispatch code.
• Validate CLI, server, and dashboard contracts with focused tests.
• Keep generated or volatile inventories out of evergreen architecture prose.

Runtime and Deployment Requirements

Surface	Requirement
Host npm install	Node.js 18+
Development and repository gates	Bun 1.0+ and Node.js 18+
Claude launches	Claude Code installed and authenticated as required by the selected profile
Droid launches	Factory Droid installed
Codex launches	Codex CLI installed
Local OAuth proxy	CCS-managed CLIProxy binary
Integrated Docker	Docker or compatible container runtime; target CLIs are not bundled

Architecture Constraints

AC-001: Profile state and shared settings are separate

Normal launches consume CCS-owned profile files and environment state. ~/.claude/settings.json is written only through an explicit persistence or approved settings-management workflow.

AC-002: Provider and target are independent axes

A provider supplies credentials and routing. A target adapter determines how a compatible CLI receives them. Unsupported combinations must fail clearly.

AC-003: Proxy trust boundary is visible

Local CLIProxy, remote CLIProxy, and direct API profiles have different transport and credential boundaries. CCS must not present them as equivalent or silently cross those boundaries.

AC-004: Source owns volatile capability data

Provider IDs, aliases, OAuth flow types, callback ports, refresh ownership, backend restrictions, and quota support must be read from the provider registries and tests. Documentation describes how to find them rather than copying a second mutable table.

Acceptance Criteria

• A user can create or select a supported profile and launch it on a compatible target without manual credential-file editing.
• Concurrent account profiles do not share target session state accidentally.
• Local and remote proxy failures follow the configured fallback policy.
• Persistent settings writes preserve unrelated keys and create a recovery path.
• Dashboard operations produce configuration compatible with CLI operations.
• Release automation publishes only from the documented branches and lanes.
• Documentation links resolve and architecture claims are traceable to source.

Risks and Mitigations

Risk	Mitigation
Provider auth contracts change	Central capability registry plus provider-specific tests
Target CLI configuration changes	Adapter boundary and compatibility checks
Credential leakage	Local storage, redaction, safe file handling, no secret logging
Remote proxy outage	Reachability checks and explicit fallback policy
Configuration corruption	Validation, backup, locking, and atomic replacement where supported
Documentation drift	Link volatile details to code; keep this document version-neutral

Related Documentation

• Codebase Summary
• Code Standards
• System Architecture
• Provider Flows
• Release Process
• Project Roadmap