CCS Codebase Summary

CCS is a TypeScript/Bun CLI and local React dashboard for selecting profiles, preparing provider credentials, and launching Claude Code, Codex CLI, Factory Droid, and compatible proxy-backed workflows. This page maps stable ownership; source and tests remain the implementation truth.

Runtime Surfaces

Surface	Entry point	Responsibility
`ccs` CLI	`src/ccs.ts`	Parse global input, register targets, resolve profiles, dispatch commands or runtimes
Runtime aliases	`package.json`	Expose packaged binaries such as `ccs`, `ccsx`, and target-specific entry points
Command handlers	`src/commands/`	Implement CCS-owned command families and help text
Local web server	`src/web-server/index.ts`	Serve configuration APIs, WebSocket updates, and the built dashboard
Dashboard	`ui/src/main.tsx`	Mount the React application used by `ccs config`
Bootstrap wrappers	`lib/`	Start the packaged CLI on Unix and Windows

Detailed user workflows and command reference live at docs.ccs.kaitran.ca. Do not infer current flags from this overview; inspect the owning handler and its tests.

CLI Domain Ownership

Domain	Main source	Owns
Command routing	`src/commands/`	Command parsing, command-specific help, setup, doctor, config, Docker, and management flows
Profile dispatch	`src/dispatcher/`	Resolve a launch into target-specific execution flows
Runtime targets	`src/targets/`	Target metadata, resolution, adapters, binary detection, and execution
Configuration	`src/config/`	Schema validation, loading, and normalized configuration access
CLIProxy	`src/cliproxy/`	Provider auth, configuration, routing, quota, lifecycle, and execution
Authentication	`src/auth/` and `src/codex-auth/`	Account and OAuth-oriented authentication flows
Channels	`src/channels/`	Official Claude channel readiness and configuration
Local proxy	`src/proxy/`	Anthropic-compatible proxy server and request/response transformers
Web API	`src/api/` and `src/web-server/`	Local dashboard services, routes, middleware, health, usage, and live updates
Shared services	`src/services/`	Cross-cutting runtime services, including structured logging
Errors	`src/errors/`	Typed error taxonomy, handling, and exit behavior
Utilities	`src/utils/`	CCS path handling and bounded shared helpers for browser, hooks, web search, image analysis, and UI support
Compatibility	`src/glmt/`, `src/copilot/`, `src/cursor/`	Legacy translation and integration-specific behavior
Packaging/runtime bins	`src/bin/`	Target-specific packaged entry points

The table is intentionally domain-level. Use repository search and nearby tests to find the current implementation instead of relying on a recursive file tree.

Profile and Target Dispatch

Profile resolution follows the repository contract in CLAUDE.md:

built-in CLIProxy providers
user-defined config.cliproxy providers
settings-based config.profiles
account-based profiles.json entries with isolated CLAUDE_CONFIG_DIR

Target selection is a separate layer:

Concern	Source
Target names, aliases, and persistence	`src/targets/target-metadata.ts`
Selection priority and `--target` parsing	`src/targets/target-resolver.ts`
Adapter interface	`src/targets/target-adapter.ts`
Adapter registry	`src/targets/target-registry.ts`
Claude implementation	`src/targets/claude-adapter.ts`
Droid implementation	`src/targets/droid-adapter.ts`
Codex implementation	`src/targets/codex-adapter.ts`

All targets currently marked persistedTarget in target metadata are valid profile targets. Runtime aliases are also derived from that metadata. Link to the source instead of maintaining a second target list here.

At startup, src/ccs.ts registers adapters. The dispatcher resolves the profile and target, asks the adapter to prepare credentials and arguments, then executes the selected CLI. Target-specific behavior belongs in the adapter or its supporting target module, not in generic command routing.

Configuration and Local State

src/utils/config-manager.ts owns CCS home resolution and honors CCS_HOME. Tests must point CCS_HOME at a temporary directory and must not touch a contributor's real ~/.ccs/ or ~/.claude/.

Configuration schemas and loaders live under src/config/. Provider- and CLIProxy-specific persistence stays under src/cliproxy/config/. Values written to settings environment maps must remain strings.

Some integrations intentionally write state owned by the launched runtime, such as Claude channel configuration or Codex configuration. Verify those boundaries in the owning module and tests before changing paths, permissions, or cleanup.

Dashboard Ownership

The dashboard is a separate TypeScript package under ui/:

Area	Path	Responsibility
Pages	`ui/src/pages/`	Route-level orchestration and settings sections
Components	`ui/src/components/`	Domain UI and shared primitives
Hooks	`ui/src/hooks/`	Server-state access and reusable UI behavior
Contexts/providers	`ui/src/contexts/` and `ui/src/providers/`	Cross-page client state
Libraries	`ui/src/lib/`	API client, localization, catalogs, formatting, and helpers

The browser communicates with routes and services under src/web-server/. When a configuration feature supports both surfaces, keep CLI and dashboard behavior aligned.

Localization codes, normalization, persistence, and fallback are owned by ui/src/lib/locales.ts. Translation resources and i18next wiring live in ui/src/lib/i18n.ts.

Logging and Operational Data

Structured CCS logging lives in src/services/logging/. Dashboard log routes and services live under src/web-server/, with UI consumers under ui/src/components/logs/ and the matching page and hooks.

Keep secrets and raw credentials out of logs. Treat legacy CLIProxy log files as a distinct source rather than folding them into CCS-owned structured logs.

Tests

Root TypeScript tests run with Bun's test runner. Bucket selection is implemented by scripts/run-test-bucket.js. The dashboard uses Vitest as configured in ui/package.json.

Coverage area	Location
Focused module behavior	`tests/unit/` and colocated `src/**/__tests__/`
Cross-module behavior	`tests/integration/`
CLI end-to-end behavior	`tests/e2e/`
Package installation and exports	`tests/npm/`
Shell and platform behavior	`tests/native/`
Docker public contracts	`tests/docker/`
Documentation checks	`tests/docs/`
Dashboard behavior	`ui/tests/` and colocated UI tests

Commands and bucket behavior are documented in tests/README.md and defined in package.json. Avoid copying test counts or pass totals into evergreen documentation.

Build and Release

Output or process	Source of truth
CLI compilation into `dist/`	root scripts in `package.json`
Dashboard build into `dist/ui/`	UI and root build scripts
Bundle verification	`scripts/verify-bundle.js`
Local CI-equivalent gate	`scripts/ci-parity-gate.sh`
Commit policy	`commitlint.config.cjs`
Branch-aware releases	`.releaserc.cjs`
GitHub automation	`.github/workflows/`

Semantic-release owns versions, changelog updates, tags, npm publication, and GitHub releases. Generated dist/ contents and release artifacts are outputs, not architectural source.

Documentation Map

Update this summary only when domain ownership, stable entry points, build boundaries, or truth sources change.

9.5 KiB Raw Blame History