> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Composite Variants

> Create CLIProxy provider variants with custom configurations

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

```bash theme={null}
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:

```bash theme={null}
ccs my-codex "your prompt"
ccs my-claude "your prompt"
```

List all variants and their status:

```bash theme={null}
ccs cliproxy
```

***

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

## Quick Start

<Steps>
  <Step title="Create via wizard">
    ```bash theme={null}
    ccs cliproxy create --composite
    ```
  </Step>

  <Step title="Or via dashboard">
    Navigate to **Dashboard → CLIProxy → Advanced Variant** and choose the
    composite variant option.
  </Step>

  <Step title="Use the variant">
    ```bash theme={null}
    ccs <variant-name> "your prompt"
    ```
  </Step>
</Steps>

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

```typescript theme={null}
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

```bash theme={null}
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):

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

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

**Example tier with fallback:**

```yaml theme={null}
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):**

1. CLI `--thinking` flag
2. Per-tier `thinking` in composite config
3. Global `thinking` config
4. 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

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

## Storage

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