Profile & Target Management
Relevant source files
The following files were used as context for generating this wiki page:
Profile & Target Management is the core orchestration layer of CCS, responsible for handling diverse LLM provider configurations and routing them to specific execution runtimes. It enables users to switch between multiple Claude subscriptions, API-backed providers like Gemini or GLM, and local models without manual configuration thrashing.
The system manages three primary entities: Accounts (isolated Claude instances), Profiles (API-based providers), and CLIProxy Variants (OAuth-based provider shortcuts). Each configuration is associated with a Target, which defines the downstream CLI runtime (e.g., claude, droid, or codex) that will execute the user's request.
Sources: AGENTS.md:27-32, README.md:58-69, src/config/loader/yaml-serializer.ts:36-65
Profile Architecture and Resolution
CCS uses a hierarchical resolution priority to determine which configuration to apply when a command is executed. This ensures that built-in provider shortcuts can be overridden by user-defined settings or account-specific contexts.
Resolution Priority
- Built-in CLIProxy providers: (e.g., Gemini, Codex, Antigravity).
- User-defined CLIProxy variants: Defined in
config.cliproxy. - Settings-based profiles: Defined in
config.profiles. - Account-based profiles: Managed via
profiles.jsonwith isolatedCLAUDE_CONFIG_DIR.
Sources: AGENTS.md:34-39, src/config/loader/yaml-serializer.ts:50-70
Workflow Logic
The following diagram illustrates the logical flow when creating an API profile and assigning its execution target.
The diagram shows the sequence of interactive prompts and resolution steps during API profile creation.
Sources: src/commands/api-command/create-command.ts:107-280
Target Routing and Runtimes
Targets represent the specific CLI binaries that CCS bridges to. The system supports dynamic routing where a single profile can be executed on different targets using flags or explicit aliases.
Supported Targets
| Target ID | Runtime CLI | Description |
|---|---|---|
claude | Claude Code | The default Anthropic CLI runtime. |
droid | Factory Droid | A specialized runtime for autonomous agents. |
codex | Codex CLI | Runtime for OpenAI-compatible and local model interactions. |
Sources: src/commands/help-command.ts:182-195, src/commands/api-command/create-command.ts:400-440
Runtime Bridges
CCS implements bridges to compatible CLIs by injecting environment variables and configuration overrides. For the codex target, the system probes the binary to ensure it supports --config overrides, which is required for managed routing.
Sources: src/web-server/services/codex-dashboard-service.ts:535-548
API Profile Lifecycle
API profiles are defined by a name, a base URL, and a mapping of models to specific tiers (Opus, Sonnet, Haiku). These settings are persisted in separate .settings.json files to avoid bloating the main configuration.
Model Tier Mapping
CCS allows granular control over which specific model ID is used for different capability tiers. This is particularly useful for providers like OpenRouter that offer multiple versions of the same model family.
Data structure relationship for API profile model tiers.
Sources: src/commands/api-command/create-command.ts:16-25, src/commands/api-command/create-command.ts:187-215
Implementation Detail: Profile Sanitization
During profile loading, CCS performs sanitization to ensure legacy or invalid targets are normalized. For example, if a profile is stored with an unsupported target like glm, the profile-reader normalizes it back to the default claude target to prevent execution failures.
Sources: tests/unit/api/profile-reader.test.ts:74-90
Configuration Management
The system supports both JSON and YAML configuration formats, with the Unified Configuration (config.yaml) being the modern standard.
Configuration Sections
- Accounts: Manages isolated
CLAUDE_CONFIG_DIRpaths for concurrent sessions. - Profiles: Stores references to API settings files.
- CLIProxy: Manages OAuth account links and provider variants.
- Proxy Routing: Defines selection rules for the local OpenAI-compatible proxy.
Sources: src/config/loader/yaml-serializer.ts:38-75
Managed Settings Storage
Configuration is stored in the user's home directory under .ccs/. The system uses getCcsDir() to resolve paths, which respects the CCS_HOME environment variable for test isolation.
Sources: AGENTS.md:28-29, src/web-server/services/codex-dashboard-service.ts:390-405
Summary
Profile & Target Management provides the flexibility to decouple LLM providers from execution runtimes. By centralizing profile resolution and target routing, CCS allows developers to maintain a stable command surface (ccs <profile>) while dynamically switching the underlying API, auth context, and CLI binary. This architecture minimizes configuration thrash and enables seamless transitions between cloud-based Claude subscriptions and local model runtimes.