Composite Variants

Composite variants let you assign different CLIProxy providers to each model tier (opus/sonnet/haiku). For example: Codex for opus, Claude for sonnet, and Codex Mini for haiku — each with its own fallback and thinking budget. CLIProxy variants are user-defined provider configurations layered on top of a base provider. Simple variants inherit all settings from a base provider with optional overrides. Composite variants extend this by assigning different providers per model tier.

Simple Variants

Create a variant from a base CLIProxy provider:

ccs cliproxy create my-codex --provider codex
ccs cliproxy create my-claude --provider claude

Options available during creation:

Custom nickname
Model override
Droid target routing: ccs cliproxy create my-codex --provider codex --target droid

Variants are stored in ~/.ccs/config.yaml under cliproxy.variants and become available as profile names:

ccs my-codex "your prompt"
ccs my-claude "your prompt"

List all variants and their status:

ccs cliproxy

Composite Variants

Quick Start

Create via wizard

ccs cliproxy create --composite

Or via dashboard

Navigate to Dashboard → CLIProxy → Advanced Variant and choose the composite variant option.

Use the variant

ccs <variant-name> "your prompt"

How It Works

Each tier (opus/sonnet/haiku) maps independently to a provider + model pair
default_tier determines which tier ANTHROPIC_MODEL resolves to when no tier is specified
Routing uses the root CLIProxy URL with model-based routing (not provider-specific URLs)
Settings written to ~/.ccs/composite-<name>.settings.json

Type Definition

interface CompositeTierConfig {
  provider: CLIProxyProvider;
  model: string;
  account?: string;
  fallback?: { provider: CLIProxyProvider; model: string; account?: string };
  thinking?: string; // 'xhigh' | 'high' | 'medium' | 'off' | numeric string
}

interface CompositeVariantConfig {
  type: 'composite';
  default_tier: 'opus' | 'sonnet' | 'haiku';
  tiers: {
    opus: CompositeTierConfig;
    sonnet: CompositeTierConfig;
    haiku: CompositeTierConfig;
  };
}

CLI Commands

ccs cliproxy create --composite    # Create with interactive wizard
ccs cliproxy edit <name>           # Edit existing variant
ccs cliproxy remove <name>         # Remove variant
ccs cliproxy list                  # List all variants (shows type column)
ccs <variant-name> "prompt"        # Use the variant

Fallback Logic

Each tier supports an optional fallback block. On provider error (4xx/5xx, quota exceeded, rate limit, ECONNREFUSED):

Detect which tier failed via model name in stderr
Apply fallback provider + model for that tier only
Retry the request with the updated config

Circular fallback is blocked — a fallback cannot point to the same provider + model as the primary.

Example tier with fallback:

cliproxy:
  variants:
    my-composite:
      type: composite
      default_tier: sonnet
      tiers:
        opus:
          provider: codex
          model: gpt-5.2
          fallback:
            provider: claude
            model: claude-opus-4-5
        sonnet:
          provider: claude
          model: claude-sonnet-4-5
        haiku:
          provider: codex
          model: gpt-5.4-mini

Per-Tier Thinking

Override the thinking budget independently per tier via thinking in CompositeTierConfig. Priority (highest to lowest):

CLI --thinking flag
Per-tier thinking in composite config
Global thinking config
Provider defaults

Valid values: xhigh, high, medium, off, or a numeric token budget string.

Dashboard CRUD

Method	Endpoint	Notes
`POST`	`/api/cliproxy`	`type: composite`, all 3 tiers required
`PUT`	`/api/cliproxy/:name`	Partial tier update supported
`DELETE`	`/api/cliproxy/:name`	Checks for active sessions before removing
`GET`	`/api/cliproxy`	Lists all variants with type, tiers, and port

Validation Rules

All 3 tiers required on create; partial updates allowed on edit
Each tier must have a valid provider and non-empty model
Circular fallback detection enforced at save time
kiro and ghcp providers require the Plus backend

Switch to the Plus backend if you need kiro or ghcp in any tier: set cliproxy.backend: plus in ~/.ccs/config.yaml.

Storage

Path	Purpose
`~/.ccs/config.yaml`	Variant definition under `cliproxy.variants[name]`
`~/.ccs/composite-<name>.settings.json`	Generated runtime settings file

Getting Started

Providers

Features

Tutorials

Composite Variants

Composite Variants

Simple Variants

Composite Variants

Quick Start

How It Works

Type Definition

CLI Commands

Fallback Logic

Per-Tier Thinking

Dashboard CRUD

Validation Rules

Storage

​Composite Variants

​Simple Variants

​Composite Variants

​Quick Start

​How It Works

​Type Definition

​CLI Commands

​Fallback Logic

​Per-Tier Thinking

​Dashboard CRUD

​Validation Rules

​Storage

Composite Variants

Simple Variants

Composite Variants

Quick Start

How It Works

Type Definition

CLI Commands

Fallback Logic

Per-Tier Thinking

Dashboard CRUD

Validation Rules

Storage