# Extended Thinking
Source: https://docs.ccs.kaitran.ca/features/ai/extended-thinking
Configure reasoning budgets across providers with unified --thinking flag
# Extended Thinking Mode
Control model reasoning depth with the cross-provider `--thinking` flag. Native
Claude launches also accept a session-scoped `--effort` override when you want
Claude's own effort control without rewriting saved settings.
Available since v7.38.0 - Extended context window support with `--1m` flag for 1M token context.
## Overview
Extended thinking allocates compute tokens for step-by-step reasoning before generating responses. Models "think out loud" internally to solve complex problems through systematic analysis.
**Use for:** Complex architecture, multi-step reasoning, debugging obscure issues, mathematical proofs, strategic planning.
## Priority Order
Thinking settings are resolved in this order (highest wins):
1. `--thinking` CLI flag
2. `CCS_THINKING` environment variable
3. `config.yaml` thinking section
## Native Claude `--effort`
When a launch stays on native Claude, CCS also accepts Claude's effort flag
directly:
```bash theme={null}
ccs --effort high "debug this regression"
ccs work --effort max "review this architecture"
```
Behavior:
* accepted values: `low`, `medium`, `high`, `xhigh`, `max`
* CCS validates the value before spawn and normalizes case
* the flag stays session-scoped; CCS does not rewrite `~/.claude/settings.json`
or `~/.ccs/config.yaml`
* CLIProxy-backed thinking flows still treat `--effort` as the CCS alias for
`--thinking`
Use `--thinking` when you want portable CCS semantics across providers. Use
`--effort` when you specifically want a native Claude one-session override.
## `CCS_THINKING` Environment Variable
Override thinking per-session without changing config:
```bash theme={null}
# Named levels
CCS_THINKING=high ccs claude "analyze this"
CCS_THINKING=auto ccs claude "complex task"
# Disable thinking
CCS_THINKING=off ccs codex "quick task"
CCS_THINKING=none ccs codex "quick task"
CCS_THINKING=disabled ccs codex "quick task"
CCS_THINKING=0 ccs codex "quick task"
# Integer budget (0-100000)
CCS_THINKING=24576 ccs claude "deep analysis"
```
**Accepted values:**
* Named levels: `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `auto`
* Off values: `off`, `none`, `disabled`, `0` (all equivalent — disable thinking)
* Integer budget: `0`–`100000`
## Two Modes
### Budget Mode (Token Count)
Specify exact token budget for thinking phase.
```bash theme={null}
ccs claude --thinking 8192 # Allocate 8K tokens
ccs claude --thinking 24576 # Deep analysis
```
### Level Mode (Named Levels)
Use predefined levels for simplified control.
```bash theme={null}
ccs codex --thinking low # Quick (1K tokens)
ccs codex --thinking medium # Standard (8K tokens)
ccs codex --thinking high # Deep (24K tokens)
ccs codex --thinking xhigh # Maximum (32K tokens)
ccs claude --thinking max # Adaptive ceiling where supported
```
**Level mappings:** minimal=512, low=1024, medium=8192, high=24576, xhigh=32768, max=adaptive ceiling
## Provider Support Matrix
| Provider | Model | Type | Range | Dynamic |
| ----------- | ----------------- | ------ | ----------------------------- | ------- |
| Claude | Claude Fable 5 | levels | low, medium, high, xhigh, max | ✓ |
| Claude | Claude Opus 5 | levels | low, medium, high, xhigh, max | ✓ |
| Claude | Claude Opus 4.8 | levels | low, medium, high, xhigh, max | ✓ |
| Claude | Claude Opus 4.7 | levels | low, medium, high, xhigh, max | ✓ |
| Claude | Claude Opus 4.6 | budget | 1024-128000 | ✓ |
| Claude | Claude Sonnet 4.6 | budget | 1024-128000 | ✓ |
| Antigravity | Claude Opus 4.6 | budget | 1024-128000 | ✓ |
| Antigravity | Claude Sonnet 4.6 | budget | 1024-64000 | ✓ |
| Gemini | Gemini 2.5 Pro | budget | 128-32768 | ✓ |
| Gemini | Gemini 3 Pro | levels | low, high | ✓ |
| Codex | GPT-5.6 Sol | levels | low, medium, high, xhigh | ✗ |
| Codex | GPT-5.6 Terra | levels | low, medium, high, xhigh | ✗ |
| Codex | GPT-5.6 Luna | levels | low, medium, high, xhigh | ✗ |
| Codex | GPT-5.4 | levels | low, medium, high, xhigh | ✗ |
| Codex | GPT-5.4 Mini | levels | low, medium, high | ✗ |
| Codex | GPT-5.2 | levels | low, medium, high, xhigh | ✗ |
* **Type:** budget (numeric) vs. levels (named presets)
* **Dynamic:** Supports `auto` mode (model decides dynamically)
Claude Opus 5 uses adaptive, level-only thinking. Select `low`, `medium`,
`high`, `xhigh`, or `max`; manual numeric thinking budgets are rejected.
Opus 5 also supports `--1m` for a 1M-token context window.
## Usage
### Auto Mode (Recommended)
```bash theme={null}
ccs claude --thinking auto # Dynamic budget selection
ccs codex --thinking medium # Fixed level selection
```
### Custom Budgets
```bash theme={null}
ccs claude --thinking 1024 # Light thinking
ccs claude --thinking 32768 # Deep analysis
ccs claude --thinking 64000 # Very deep analysis
```
### Named Levels
```bash theme={null}
ccs codex --thinking off # Disable thinking
ccs codex --thinking medium # Balanced
ccs codex --thinking xhigh # Maximum effort
ccs claude --thinking max # Adaptive max on Fable 5 / Opus 4.8
```
### Cross-Type Compatibility
CCS automatically converts between budgets and levels.
```bash theme={null}
ccs claude --thinking high # → 24576 tokens
ccs codex --thinking 8192 # → "medium" level
```
## Auto-Capping Behavior
CCS validates values and auto-adjusts invalid inputs.
### Budget Clamping
```bash theme={null}
ccs claude --thinking 200000 # → Clamped to 128000 (max)
```
### Level Capping
```bash theme={null}
ccs codex --thinking xhigh # → Capped to "high" (GPT-5 Mini)
ccs codex --thinking max # → Mapped to "xhigh" when max is not native
```
### Fuzzy Matching
```bash theme={null}
ccs codex --thinking hi # → "high"
ccs codex --thinking med # → "medium"
```
## Cost Implications
Higher budgets = more tokens = higher cost.
* **low (1K):** Minimal cost, fast
* **medium (8K):** Moderate cost, balanced
* **high (24K):** Higher cost, deep analysis
* **xhigh (32K):** Maximum cost, maximum depth
* **Custom (32K-128K):** Very high cost, provider/model dependent
**Best practices:** Use `auto` for optimization, reserve high budgets for complex problems, start with `low`/`medium` for routine tasks.
## Troubleshooting
### Model Doesn't Support Thinking
**Error:** `Model gemini-claude-sonnet-4-5 does not support extended thinking`
**Solution:** Use thinking-enabled variants (e.g., `gemini-claude-sonnet-4-5-thinking`) or switch to a supported reasoning-first profile such as `ccs km` when you need Kimi API reasoning. Legacy `ccs glmt` remains compatibility-only.
### Budget Exceeds Maximum
**Warning:** `Thinking budget 200000 exceeds maximum. Clamped to 128000.`
**Solution:** Use budget within range or switch to model with higher limit.
### Level Not Supported
**Warning:** `Level "xhigh" not valid for gpt-5-mini. Mapped to "high".`
**Solution:** CCS auto-maps to closest valid level. Check support matrix.
### Dynamic Thinking Unavailable
**Warning:** `Model does not support dynamic/auto thinking`
**Solution:** Specify explicit level or budget. Check "Dynamic" column in matrix.
## `ccs config thinking` Command
Manage thinking configuration interactively or via flags:
```bash theme={null}
# Show current thinking config
ccs config thinking
# Set thinking mode
ccs config thinking --mode auto # Dynamic tier-based defaults
ccs config thinking --mode off # Disable thinking entirely
ccs config thinking --mode manual # Use explicit override
# Persistent override (applies to all providers)
ccs config thinking --override high # Set persistent override level
ccs config thinking --override 24576 # Set persistent override budget
ccs config thinking --clear-override # Remove persistent override
# Per-tier defaults
ccs config thinking --tier opus high # Set opus tier to "high"
ccs config thinking --tier sonnet medium # Set sonnet tier to "medium"
ccs config thinking --tier haiku low # Set haiku tier to "low"
# Per-provider overrides
ccs config thinking --provider-override gemini opus xhigh
ccs config thinking --provider-override agy sonnet high
ccs config thinking --clear-provider-override gemini # Clear all gemini overrides
ccs config thinking --clear-provider-override gemini opus # Clear gemini opus only
```
### Dashboard Thinking Settings
The CCS Dashboard includes a **Thinking** settings panel with:
* **Mode selector** — auto / off / manual
* **Persistent Override** panel — set a global level that overrides tier defaults
* **Tier defaults** — configure opus/sonnet/haiku default levels
* **Provider Overrides** section — per-provider tier level customization
## Related
* [CLI Flags Reference](/reference/cli-flags) - `--thinking` flag syntax, `CCS_THINKING` env var
* [Antigravity Provider](/providers/oauth/agy) - Budget mode, 100K max
* [Gemini Provider](/providers/oauth/gemini) - Budget/level hybrid
* [Codex Provider](/providers/oauth/codex) - Level-based, maxLevel caps
* [GLMT Deprecation](/features/ai/glmt-controls) - Legacy compatibility and migration guidance
## Extended Context Window
Available since v7.38.0
Enable 1M token context window for supported models using the `--1m` flag.
### Usage
```bash theme={null}
# Enable 1M context
ccs claude --1m "analyze this large codebase"
# Disable (use default context)
ccs claude --no-1m "quick prompt"
# Combine with thinking mode
ccs claude --thinking auto --1m "deep analysis of large project"
```
### How It Works
The `--1m` flag appends `[1m]` suffix to model names, routing to extended context variants:
```bash theme={null}
# Without --1m
gemini-claude-sonnet-4-5
# With --1m
gemini-claude-sonnet-4-5[1m]
```
### Provider Support
**Auto-Enabled:**
* Native Gemini models (always use 1M context by default)
**Opt-In:**
* Claude models via Gemini proxy
* Antigravity models
* Codex models
**Not Supported:**
* Settings-based profiles (GLM, KM, custom APIs)
* Local models (Ollama)
### Best Practices
**When to use `--1m`:**
* Large codebase analysis
* Multi-file refactoring
* Documentation generation across many files
* Complex architectural planning
**When NOT to use:**
* Simple queries (wastes quota)
* Short prompts (no benefit)
* Rate-limited scenarios (uses more quota faster)
### Cost Implications
Extended context consumes quota faster. Use selectively for tasks requiring large context windows.
### Disable Extended Context
```bash theme={null}
# Force standard context
ccs claude --no-1m "your prompt"
```
Useful when:
* Quota conservation needed
* Faster response time preferred
* Task doesn't require large context
# GLMT Deprecation
Source: https://docs.ccs.kaitran.ca/features/ai/glmt-controls
Migration guidance for legacy ccs glmt users
# GLMT Deprecation
`ccs glmt` is deprecated and no longer a supported public product surface. It
remains available only as a compatibility path for legacy scripts and configs
that still use the old profile name or legacy `glmt.settings.json` payloads.
## Use This Instead
| Need | Supported command | Notes |
| -------------------------------- | ----------------- | ---------------------------------------------- |
| Z.AI API profile | `ccs glm` | Direct Z.AI API profile for standard GLM usage |
| Reasoning-first Kimi API profile | `ccs km` | Direct Kimi for Coding profile |
| Long-context Kimi via OAuth | `ccs kimi` | CLIProxy OAuth provider for device-code auth |
## Migration
1. Replace `ccs glmt` invocations in scripts, snippets, and local aliases with
`ccs glm` or `ccs km`.
2. For new setups, create `glm` or `km` from the dashboard or with
`ccs api create --preset glm|km`.
3. Keep legacy `glmt` only until old automation, bookmarks, and docs links are updated.
## Legacy Behavior That Still Exists
* `ccs glmt` now routes through the normal settings-profile flow after CCS
normalizes legacy proxy-only settings to the direct GLM endpoint at runtime.
* Existing `glmt.settings.json` files remain readable during migration.
* CCS still prints explicit deprecation warnings so old scripts are not silently
treated as a supported product surface.
* No new setup or feature guidance is published for GLMT.
## When You Might Still Encounter GLMT
* Existing shell scripts or CI jobs still call `ccs glmt`
* Old settings files still include `glmt.settings.json`
* Historical links still point to this page
## Related
* [CLI Commands](/reference/cli-commands) - Supported commands and legacy note
* [CLI Flags](/reference/cli-flags) - General CLI and CLIProxy diagnostics
* [API Profiles](/providers/concepts/api-profiles) - Supported `glm` and `km` setup
* [Kimi Provider](/providers/oauth/kimi) - `ccs kimi` OAuth and `ccs km` API details
# Image Analysis
Source: https://docs.ccs.kaitran.ca/features/ai/image-analysis
MCP-first image and PDF analysis for third-party CCS launches
# Image Analysis
CCS provides first-class image and PDF analysis for third-party launches that do
not have reliable native vision support. Native Claude accounts keep
Anthropic's built-in image flow; third-party routes get a CCS-managed local
`ImageAnalysis` MCP tool when the runtime is healthy.
Supported file types include common image formats such as `.jpg`, `.png`,
`.webp`, `.gif`, `.heic`, `.bmp`, `.tiff`, plus `.pdf`.
## Overview
The current routing model is MCP-first:
```text theme={null}
Claude -> ccs-image-analysis MCP -> CCS provider route -> /api/provider//v1/messages
```
CCS also appends a short steering hint so Claude prefers `ImageAnalysis` over
raw `Read` for local images and PDFs.
## Launch Behavior
| Profile type | Behavior |
| ----------------------------------------------------------------- | --------------------------------------------- |
| Claude `default` / `account` | Native Claude vision or native `Read` |
| Third-party settings, CLIProxy, Copilot | Managed `ImageAnalysis` MCP when ready |
| Third-party with degraded MCP but usable provider-backed analysis | Legacy CCS `Read` hook compatibility fallback |
| Third-party with runtime/auth/proxy failure | Native `Read` fallback |
Healthy Claude-target launches suppress the legacy CCS image `Read` hook so the
managed MCP tool stays authoritative.
## Quick Start
```bash theme={null}
# Inspect current image-analysis state
ccs config image-analysis
# Enable or disable globally
ccs config image-analysis --enable
ccs config image-analysis --disable
# Increase timeout for large documents
ccs config image-analysis --timeout 120
# Set provider-specific models
ccs config image-analysis --set-model agy gemini-3-1-flash-preview
ccs config image-analysis --set-model codex gpt-5.1-codex-mini
# Pick a fallback backend for bridge-backed profiles
ccs config image-analysis --set-fallback agy
# Override the backend for a specific settings profile
ccs config image-analysis --set-profile-backend glm agy
ccs config image-analysis --clear-profile-backend glm
```
## Configuration
```yaml theme={null}
image_analysis:
enabled: true
timeout: 60
fallback_backend: gemini
provider_models:
agy: gemini-3-1-flash-preview
codex: gpt-5.1-codex-mini
profile_backends:
glm: agy
```
### Prompt Templates
CCS installs editable prompt templates under:
```text theme={null}
~/.ccs/prompts/image-analysis/
```
Templates:
* `default.txt`
* `screenshot.txt`
* `document.txt`
CCS automatically selects the screenshot template for screenshot-like filenames,
the document template for PDFs, and the default template otherwise.
## What CCS Repairs Automatically
CCS now self-heals stale managed image-analysis state in three places:
1. Healthy Claude-target launches remove stale CCS-managed image hooks from the
active profile settings before launch.
2. Saving or provisioning from `Settings -> Image` repairs the managed MCP
runtime files, syncs the `ccs-image-analysis` entry into isolated Claude
configs, and removes stale CCS-managed hooks from `~/.ccs/*.settings.json`.
3. `ccs doctor --fix` repairs invalid image-analysis config, removes stale
CCS-managed hooks, and resyncs the managed MCP entry into isolated configs.
## Runtime Details
Key runtime environment variables:
| Variable | Purpose |
| ------------------------------------- | ---------------------------------------------------------------- |
| `CCS_IMAGE_ANALYSIS_SKIP` | Disable image analysis for the current launch |
| `CCS_IMAGE_ANALYSIS_SKIP_HOOK` | Suppress only the legacy `Read` hook while keeping MCP available |
| `CCS_IMAGE_ANALYSIS_RUNTIME_BASE_URL` | Explicit CCS runtime base URL |
| `CCS_IMAGE_ANALYSIS_RUNTIME_PATH` | Provider route such as `/api/provider/agy` |
| `CCS_IMAGE_ANALYSIS_RUNTIME_API_KEY` | Explicit CCS runtime auth key |
| `CCS_IMAGE_ANALYSIS_MODEL` | Force a single model for the launch |
| `CCS_DEBUG` | Verbose runtime logging |
## Troubleshooting
### Claude still uses `Read`
* Confirm `ccs config image-analysis` still shows `enabled: true`
* Check the active profile resolves to a usable backend
* Run `ccs doctor --fix` to repair stale managed hooks or missing MCP sync
* Run with `CCS_DEBUG=1` to inspect runtime preparation
### ImageAnalysis is not exposed
* Verify the resolved backend is authenticated
* Verify the local or remote CLIProxy target is reachable
* Check inherited Claude config directories for the managed
`ccs-image-analysis` MCP entry
### The wrong backend or model is being used
* Inspect `fallback_backend` and `profile_backends` in `ccs config image-analysis`
* Check whether the profile is bridge-backed or using a direct CLIProxy provider
* Set an explicit provider model with `--set-model` if the default is not what
you want
### I need proof that requests go directly to the provider route
Run with `CCS_DEBUG=1` and inspect the resolved runtime path. It should target a
provider-scoped route such as:
```text theme={null}
/api/provider/agy/v1/messages
```
## Related
* [CLIProxy API](/features/proxy/cliproxy-api)
* [WebSearch](/features/ai/websearch)
# WebSearch
Source: https://docs.ccs.kaitran.ca/features/ai/websearch
Web search fallback for third-party providers
# WebSearch Fallback
Third-party profiles cannot use Anthropic's native WebSearch. CCS provides automatic web search via CLI tools with intelligent fallback.
## Overview
CCS intercepts WebSearch requests from Claude Code and routes them through available CLI tools.
## How It Works
| Profile Type | WebSearch Method |
| -------------------- | ----------------------- |
| Claude (native) | Anthropic WebSearch API |
| Third-party profiles | CLI Tool Fallback Chain |
## Fallback Chain
CCS tries tools in priority order until one succeeds:
| Priority | Tool | Auth | Install |
| -------- | ---------- | ------------ | ------------------------------------------------ |
| 1st | Gemini CLI | OAuth (free) | `npm install -g @google/gemini-cli` |
| 2nd | OpenCode | OAuth (free) | `curl -fsSL https://opencode.ai/install \| bash` |
| 3rd | Grok CLI | API Key | `npm install -g @vibe-kit/grok-cli` |
## Configuration
Configure via dashboard (**Settings** page) or `~/.ccs/config.yaml`:
```yaml theme={null}
websearch:
enabled: true # Enable/disable (default: true)
providers:
gemini:
enabled: true # Use Gemini CLI (default: true)
model: gemini-2.5-flash # Model to use
opencode:
enabled: true # Use OpenCode as fallback
grok:
enabled: false # Requires XAI_API_KEY
```
CCS resolves one configuration snapshot for each new Claude launch. Provisioning,
hook environment, and steering for that launch all use the same snapshot; a later
config edit does not change the already prepared session.
If you set `websearch.enabled: false`, third-party Claude launches still keep
native `WebSearch` disallowed. CCS omits its steering prompt and marks the
managed hook to skip execution for that launch, so no active WebSearch hook state
or provider fallback runs.
## Setup
```bash theme={null}
npm install -g @google/gemini-cli
```
Run once to complete OAuth:
```bash theme={null}
gemini
```
Check that websearch works:
```bash theme={null}
ccs codex "search for the latest TypeScript features"
```
## Provider Details
* **Auth**: Free Google OAuth
* **Limit**: 1000 requests/day
* **Quality**: Excellent search relevance
* **Setup**: `gemini` to authenticate via browser
* **Auth**: Free OAuth
* **Limit**: Varies
* **Quality**: Good for code-related searches
* **Setup**: Follow installer prompts
* **Auth**: Requires `XAI_API_KEY`
* **Limit**: Based on API plan
* **Quality**: Real-time web access
* **Setup**: Set env var and install
## Troubleshooting
Verify CLI tools are installed:
```bash theme={null}
which gemini opencode grok
```
Re-authenticate the failing tool:
```bash theme={null}
gemini # Opens browser for OAuth
```
Switch to a faster fallback:
```yaml theme={null}
websearch:
providers:
gemini:
model: gemini-2.0-flash-lite
```
**Gemini CLI** is recommended - free OAuth authentication with 1000 requests/day. Just run `gemini` once to authenticate via browser.
# Account Safety
Source: https://docs.ccs.kaitran.ca/features/config/account-safety
Cross-provider isolation, ban detection, and quota monitoring to protect Google accounts
# Account Safety
Automatic protections to prevent Google account bans when using multiple OAuth providers simultaneously.
## Overview
When the same Google email is authenticated across multiple providers (gemini, agy, codex), simultaneous usage can trigger Google's abuse detection. CCS automatically isolates accounts to prevent this.
This feature addresses [Issue #509](https://github.com/kaitranntt/ccs/issues/509). If you use the same Google email across gemini and agy, enable cross-provider isolation.
## Cross-Provider Isolation
### How It Works
On session launch, CCS scans all providers for emails appearing in 2+ Google OAuth providers
Conflicting accounts in other providers are temporarily paused
Only one provider uses the shared email at a time
On session exit, paused accounts are restored automatically
**Example:** If `john@gmail.com` is authenticated in both `gemini` and `agy`, starting a `gemini` session auto-pauses the `agy` account for `john@gmail.com`.
### Crash Recovery
If CCS crashes without restoring paused accounts:
* Next launch detects stale sessions (dead PIDs)
* Automatically restores accounts from dead processes
* Persistence file: `~/.ccs/cliproxy/auto-paused.json`
## Ban Detection
CCS monitors for ban-related error patterns during sessions:
**Detected Patterns:**
* `disabled in this account`
* `violation of terms of service`
* `account has been disabled/suspended/banned`
**On Detection:**
1. Affected account is auto-paused immediately
2. No further retries on banned account
3. Warning displayed with box border
## Runtime Quota Monitoring
Available since v7.42.0. Monitors quota during active sessions, not just at startup.
### Quota Warning
When quota falls below 20%, CCS displays a warning:
```
╔═══════════════════════════════════════╗
║ [!] Quota below 20% for codex ║
║ Daily: 48/50 messages remaining ║
╚═══════════════════════════════════════╝
```
### Quota Exhaustion
When quota is fully exhausted:
1. Applies cooldown period to exhausted account
2. Finds healthy alternative account (if available)
3. Switches default account automatically
4. Logs the switch for transparency
Before local CLIProxy startup, CCS also checks the active provider account pool.
If a non-default account is already quota-exhausted and another healthy account
exists, CCS temporarily pauses the exhausted account so CLIProxy does not keep
routing requests to it. The pause uses the same cooldown metadata as runtime
quota exhaustion and resumes automatically when the cooldown expires.
## Antigravity Responsibility Checklist
Available since v7.49.0
When adding a new Antigravity account via the dashboard, a responsibility checklist is displayed. Users must acknowledge guidelines before the account is activated:
* Account usage policies
* Rate limit awareness
* Fair use expectations
This checklist appears in the "Add Account" dialog for the Antigravity provider and helps prevent unintentional policy violations.
## Configuration
Account safety runs automatically with no configuration needed. Behavior is controlled internally based on provider auth files.
### Manual Account Management
```bash theme={null}
# Pause an account manually
ccs cliproxy pause
# Resume a paused account
ccs cliproxy resume
# Check status of all accounts
ccs cliproxy status
```
## Token Storage
OAuth tokens are stored locally with restricted permissions:
| Path | Permission | Contents |
| ---------------------------------- | ------------------- | --------------------------------------------------- |
| `~/.ccs/cliproxy/auth/` | `0o600` (user-only) | Individual OAuth token files per provider account |
| `~/.ccs/cliproxy/accounts.json` | `0o600` | Account registry with pause state and tier metadata |
| `~/.ccs/cliproxy/auto-paused.json` | `0o600` | Auto-pause session tracking |
Tokens are never transmitted outside of the local CLIProxy instance. CLIProxy listens on `127.0.0.1:8317` by default.
## Dashboard Authentication
If you expose the dashboard on a non-loopback address (e.g. `ccs config --host 0.0.0.0`), enable password protection first:
```bash theme={null}
# Set up dashboard authentication
ccs config auth setup
```
This adds HTTP basic auth to the dashboard server. Without it, any device on your network can access your account configuration and OAuth tokens.
Always run `ccs config auth setup` before using `ccs config --host 0.0.0.0` on a shared or untrusted network.
## Best Practices
* Use separate Google accounts for each OAuth provider (gemini, agy, codex)
* Do not reuse the same email across gemini and agy (see [Issue #509](https://github.com/kaitranntt/ccs/issues/509))
* Enable dashboard auth before exposing the dashboard beyond localhost
* Review the Antigravity responsibility checklist when adding new accounts
* CCS is provided as-is and does not take responsibility for account bans or access loss resulting from usage
## Storage
| Path | Purpose |
| ---------------------------------- | --------------------------------- |
| `~/.ccs/cliproxy/auto-paused.json` | Auto-pause session tracking |
| `~/.ccs/cliproxy/accounts.json` | Account registry with pause state |
| `~/.ccs/cliproxy/auth/` | OAuth token files per provider |
## Troubleshooting
### Account Stuck in Paused State
**Symptom:** Account not rotating after crash
**Solution:**
```bash theme={null}
# Check paused accounts
ccs cliproxy status
# Manually resume
ccs cliproxy resume
```
### False Ban Detection
**Symptom:** Account paused but not actually banned
**Solution:** Resume manually and monitor:
```bash theme={null}
ccs cliproxy resume
```
## Next Steps
Configure multiple accounts per provider
Monitor account status via web UI
# Composite Variants
Source: https://docs.ccs.kaitran.ca/features/config/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
```bash theme={null}
ccs cliproxy create --composite
```
Navigate to **Dashboard → CLIProxy → Advanced Variant** and choose the
composite variant option.
```bash theme={null}
ccs "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-.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 # Edit existing variant
ccs cliproxy remove # Remove variant
ccs cliproxy list # List all variants (shows type column)
ccs "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
Circular fallback is blocked — a fallback cannot point to the same provider + model as the primary.
**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
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-.settings.json` | Generated runtime settings file |
# Dashboard Localization
Source: https://docs.ccs.kaitran.ca/features/config/i18n
Multi-language support for the CCS dashboard — English, Simplified Chinese, Vietnamese, Japanese, Korean, and Brazilian Portuguese
# Dashboard Localization
Brazilian Portuguese (`pt-BR`) joined the dashboard in v8.8.1-dev.8. Korean
(`ko`) has been available since v7.79.1-dev.2.
The CCS dashboard supports multiple display languages. All 40+ components are fully translated, including Analytics, OAuth Providers, API Profiles, Settings, Shared Data, and more.
## Supported Languages
| Locale | Language | Added In | Coverage |
| ------- | -------------------- | ------------- | -------------- |
| `en` | English | v1.0 | Source locale |
| `zh-CN` | Simplified Chinese | v7.51.0 | Full dashboard |
| `vi` | Vietnamese | v7.51.0 | Full dashboard |
| `ja` | Japanese | v7.53.0 | Full dashboard |
| `ko` | Korean | v7.79.1-dev.2 | Full dashboard |
| `pt-BR` | Brazilian Portuguese | v8.8.1-dev.8 | Full dashboard |
## Switching Language
The language switcher is in the top navigation bar of the dashboard.
```bash theme={null}
# Open dashboard
ccs config
# Click the language selector in the top-right corner
```
**Language detection order:**
1. User selection (persisted in `localStorage`)
2. Browser language preference (`navigator.language`)
3. Falls back to English (`en`)
Your selection is saved automatically — no page reload needed.
## Coverage
All major dashboard sections are fully localized:
Usage trends, cost breakdowns, model usage charts, session stats
Provider status, account lists, quota displays, auth flows
Profile creation wizard, preset catalog, settings forms
CLIProxy sync, preferences, dashboard auth, update settings
Commands, skills, agents tabs, search, markdown viewer
Auth monitor, health status, token state indicators
## Next Steps
Full dashboard feature documentation
Usage tracking and cost analysis
# Shared Data
Source: https://docs.ccs.kaitran.ca/features/config/shared-data
Inspect shared commands, skills, and agents from the CCS dashboard
# Shared Data
Shared Data is the routed dashboard workspace for the reusable Claude assets
that CCS exposes across profiles: commands, skills, and agents.
## Access
```bash theme={null}
ccs config
# Sidebar -> Accounts -> Shared Data
# Direct route -> /shared
```
## What It Reads
Shared Data is an inspection layer on top of the shared asset chain:
* `~/.claude/` remains the authoritative source
* `~/.ccs/shared/` is the CCS access layer
* profile instances read shared assets through that chain
For non-bare profiles, this chain also shares `settings.json` and the user
instructions in `CLAUDE.md`. The Shared Data browser itself lists only
commands, skills, and agents.
On Windows, CCS can fall back to copies when symlinks are unavailable.
## Current Layout
### Header
The current page header surfaces three live counts:
* **Total Shared** across commands, skills, and agents
* **Current tab total**
* **Visible** items after search filtering
It also shows a markdown-detail badge and an optional filter badge when a query
is active.
### Left Pane
The left pane is the browser:
* tab switcher for **Commands**, **Skills**, and **Agents**
* live item counts per tab
* search across item name, description, and path
* retry handling when list reads fail
### Right Pane
The right pane is the detail viewer:
* rendered markdown or raw content for the selected item
* item kind badge
* path and metadata display
* loading and retry states for the selected item
## Asset Discovery Rules
| Kind | Location | Discovery |
| -------- | --------------------- | ---------------------------------------------------- |
| Commands | `~/.claude/commands/` | recursive `.md` discovery |
| Skills | `~/.claude/skills/` | directories containing `SKILL.md` |
| Agents | `~/.claude/agents/` | agent directories or standalone markdown agent files |
## Configuration Warnings
If the shared-data chain is invalid, the workspace shows a configuration alert
and points you back to:
```bash theme={null}
ccs sync
```
The page can still show partial results while counts or content retry, but a
broken shared chain should be fixed before you trust the inventory.
## CLI Parity
```bash theme={null}
ccs sync
ccs doctor
ccs auth resources
ccs auth resources --mode shared|profile-local
```
Use the dashboard when you want discovery and reading. Use the CLI when you
need repair or automation.
## Per-Profile Shared Resource Policy
Each account profile is either **shared** (plugins, settings, `CLAUDE.md`,
commands, skills, and agents linked from `~/.claude/`) or **profile-local** (no
linking; the profile carries its own resource set, equivalent to creating with
`--bare`). New non-bare profiles use shared mode by default.
Switch modes from the dashboard or CLI:
| Surface | How |
| ---------- | ----------------------------------------------------------- |
| Dashboard | Accounts -> profile row -> "Edit Shared Resources" dialog |
| CLI | `ccs auth resources --mode shared\|profile-local` |
| Inspection | `ccs auth resources [--json]` |
Profile-local mode is useful for sandboxed accounts that must not inherit your
global Claude plugins, skills, settings, or instructions.
## Shared `CLAUDE.md`
`~/.claude/CLAUDE.md` is the canonical user-instructions file. Shared profiles
use this chain:
```text theme={null}
~/.ccs/instances//CLAUDE.md
-> ~/.ccs/shared/CLAUDE.md
-> ~/.claude/CLAUDE.md
```
If the canonical file and all previous copies are missing, CCS creates an empty
Markdown file. It does not seed `CLAUDE.md` with JSON.
Reconciliation is canonical-first:
| Existing state | Result |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Canonical file exists | Canonical content wins; divergent copies are preserved beside their old path with a `.ccs-shared-conflict` suffix. |
| Canonical file is missing and one byte-for-byte variant exists | CCS adopts that variant as the canonical file. |
| Canonical file is missing and multiple distinct variants exist | CCS preserves every variant with a `.ccs-shared-conflict` suffix, creates an empty canonical file, and asks you to recover one explicitly. Modification time is not used to choose. |
To recover a conflict, inspect the preserved files, put the intended content in
`~/.claude/CLAUDE.md`, then start each affected shared profile so CCS can
restore its managed link. Keep the conflict copies until you confirm the
instructions load correctly.
## API Endpoints
| Endpoint | Purpose |
| --------------------------------------- | ------------------------------- |
| `GET /api/shared/commands` | list shared commands |
| `GET /api/shared/skills` | list shared skills |
| `GET /api/shared/agents` | list shared agents |
| `GET /api/shared/content?type=X&path=Y` | load selected item content |
| `GET /api/shared/summary` | fetch counts and symlink status |
## Related
* [Accounts Workspace](/features/dashboard/accounts-workspace)
* [CLI Commands](/reference/cli-commands)
* [File Locations](/reference/file-locations)
# Updates Center
Source: https://docs.ccs.kaitran.ca/features/config/updates-center
Action-oriented inbox for rollout tasks, support matrix, and integration status tracking
# Updates Center
The Updates Center is a dashboard page that tracks rollout tasks, support status for integrations, and actionable setup steps.
## Overview
Access the Updates Center at `http://localhost:3000/updates` via the CCS dashboard.
**Key Features:**
* **Action inbox** — notices with "Do Next" tasks you can mark done/dismissed
* **Support matrix** — status of each integration (Target CLI, CLIProxy, API, WebSearch)
* **Progress tracking** — per-notice state persisted in browser localStorage
## Layout
The page uses a two-panel layout:
**Left panel (inbox list):**
* Stat cards showing "Needs Action" and "Done" counts
* Search box (searches titles, summaries, commands, highlights)
* View mode tabs: Action Required | Done | All
* Scrollable notice list sorted by date (newest first)
**Right panel (detail view):**
* Notice header with title, summary, status badges
* Action buttons: Mark Done, Dismiss, Reopen
* "Do Next" card with actionable items (dashboard links + CLI commands)
* "Impacted Integrations" card showing affected support entries
* "Why It Matters" highlights
## Notice Progress
Each notice tracks a progress state stored in browser localStorage:
| State | Badge | Meaning |
| ----------- | ------------ | ---------------------------- |
| `new` | Needs Action | Unread, requires attention |
| `seen` | In Review | Clicked once, being reviewed |
| `done` | Done | Completed by user |
| `dismissed` | Dismissed | Intentionally skipped |
Clicking an inbox item auto-transitions `new` → `seen`. Use action buttons to mark `done` or `dismissed`.
**Storage key:** `ccs:updates:notice-progress:v1` (localStorage JSON)
## Support Entries
Each notice links to **support entries** representing integrations:
| Scope | Label | Examples |
| ----------- | ----------------- | -------------------------- |
| Target CLI | Target CLI | Claude Code, Factory Droid |
| CLIProxy | CLIProxy Provider | Codex, Gemini, Antigravity |
| API Profile | API Profile | Custom API endpoints |
| WebSearch | WebSearch | OpenCode WebSearch |
Each entry shows:
* **Name** and scope badge
* **Three pillars:** Base URL source, Auth method, Model selection
* **Dashboard link** and **CLI command** with copy button
## Action Types
"Do Next" items are either:
1. **Route actions** — buttons navigating to dashboard sections (e.g., "Open API Profiles" → `/providers`)
2. **Command actions** — CLI snippets with copy button (e.g., `ccsd glm`, `ccs codex --target droid "prompt"`)
## Access
The Updates Center is accessible via direct URL navigation. It is not shown in the main sidebar — designed as an on-demand reference page.
```bash theme={null}
# Open dashboard, then navigate to /updates
ccs config
# → http://localhost:3000/updates
```
All content is static — published as part of CCS releases. No external API calls or CMS.
## Related
* [Dashboard](/features/dashboard/overview) — Main dashboard overview
* [Droid Adapter](/features/workflow/droid-adapter) — Multi-target routing
* [CLIProxy API](/features/proxy/cliproxy-api) — OAuth provider management
# Accounts Workspace
Source: https://docs.ccs.kaitran.ca/features/dashboard/accounts-workspace
Manage CCS auth profiles, continuity groups, and Claude pool handoff from the dashboard
# Accounts Workspace
The Accounts workspace at `/accounts` is the dashboard surface for **CCS auth
profiles**. Use it when you manage `ccs auth` profiles, continuity groups, and
default-account behavior. Use the Claude provider inside `/cliproxy` instead
when the account should live in the CLIProxy pool.
## Access
```bash theme={null}
ccs config
# Sidebar -> Identity & Access -> Accounts
# Direct route -> /accounts
```
## What It Covers
* create new CCS auth profiles without leaving the dashboard
* follow the recommended two-account route: keep tokens isolated and choose
the account explicitly at runtime
* inspect continuity and context-group relationships
* see when plain `ccs` is using a different resume lane than an account profile
* review migration follow-up for legacy inferred sharing
* jump into the Claude pool auth flow when an account belongs in CLIProxy
## Layout
### Left Action Rail
The left rail is the command surface for day-to-day account work:
* **Create Account** opens the profile creation dialog
* **Auth Claude In Pool** deep-links into `/cliproxy?provider=claude&action=auth`
* **Open Claude Pool Settings** jumps to the Claude provider inside `/cliproxy`
* **Migration Follow-up** appears when legacy inferred sharing still needs confirmation
* **Quick Commands** mirrors the most common CLI flows with copy buttons
### Main Workspace
The main panel is a continuity-first view of your auth profiles:
* **Continuity overview** summarizes isolated lanes, shared lanes, deeper-continuity readiness, and CLIProxy-adjacent counts
* **Route guide** explains isolated account usage, shared settings and instructions, and opt-in history sync
* **Account matrix** lists CCS auth profiles, default-account state, and group relationships
* **Badges** call out the workspace scope and history-sync posture before you edit anything
The workspace separates three concepts that are easy to confuse:
| Concept | Default | How to inspect |
| ------------------------------------ | ------------------------------------ | ---------------------------------------- |
| Credentials and tokens | isolated per account profile | `ccs auth show ` |
| `settings.json` and user `CLAUDE.md` | shared for non-bare account profiles | route guide or `ccs auth show ` |
| Local history and resume continuity | isolated unless sharing is enabled | continuity overview and account matrix |
Non-bare account profiles link settings and user instructions through CCS
shared state:
```text theme={null}
~/.ccs/instances//settings.json
-> ~/.ccs/shared/settings.json
-> ~/.claude/settings.json
~/.ccs/instances//CLAUDE.md
-> ~/.ccs/shared/CLAUDE.md
-> ~/.claude/CLAUDE.md
```
This keeps normal Claude settings and instructions aligned without copying
account credentials. `~/.claude/CLAUDE.md` is canonical; CCS preserves
divergent copies for explicit recovery instead of overwriting it. History sync
is separate and remains opt-in.
### Mobile View
On smaller screens the workspace collapses into a stacked layout. The same
actions remain available, but the side rail becomes a compact card above the
account matrix.
## Relationship To Shared Data
`/accounts` and `/shared` live in the same sidebar group, but they solve
different problems:
| Route | Use it for |
| ----------- | ------------------------------------------------------------------ |
| `/accounts` | CCS auth profiles, continuity, default-account management |
| `/shared` | shared resource policy plus browsable commands, skills, and agents |
If you need to inspect shared commands, skills, or agents, or recover a
`CLAUDE.md` conflict, see [Shared Data](/features/config/shared-data).
## CLI Parity
The workspace stays aligned with the CLI rather than replacing it:
```bash theme={null}
ccs auth create work
ccs auth create personal
ccs work
ccs personal
ccs auth create work --share-context --context-group sprint-a --deeper-continuity
ccs auth show work
ccs auth backup default
ccs auth default work
ccs cliproxy auth claude
```
Use the dashboard when you want structure and visibility. Use the CLI when you
need scripts, terminals, or versioned setup.
## Related
* [Claude Accounts](/providers/concepts/claude-accounts)
* [CLIProxy API](/features/proxy/cliproxy-api)
* [Shared Data](/features/config/shared-data)
# Analytics
Source: https://docs.ccs.kaitran.ca/features/dashboard/analytics
Track usage metrics, costs, and session statistics across all providers
# Analytics Dashboard
The Analytics dashboard provides comprehensive visibility into your AI usage patterns, costs, and performance metrics across all configured providers — including Claude, CLIProxy OAuth providers, and CLIProxy multi-provider sources.
## Overview
Access analytics through the dashboard:
```bash theme={null}
ccs config
# Navigate to Analytics tab
```
## Data Sources
Available since v7.51.0 — unified multi-provider analytics
CCS aggregates usage data from three sources into a single unified view:
Local session data from `~/.claude/` — costs, tokens, session history for Claude account profiles
Usage from all configured CCS profiles (GLM, API profiles, account profiles)
Aggregated usage from all CLIProxy OAuth providers (Gemini, Codex, AGY, GHCP, Kimi, etc.)
### CLIProxy Background Sync
CLIProxy usage data syncs automatically every **5 minutes** in the background:
* Snapshot stored at `~/.ccs/cache/cliproxy-usage/latest.json`
* Dashboard reads from snapshot for instant load (no blocking API calls)
* Manual refresh available via the refresh button or API endpoint
## Key Metrics
Five summary cards display high-level metrics:
Combined input/output tokens across all providers
Aggregate spending across Claude, Gemini, GPT, GLM, Qwen models
Tokens served from cache, reducing API costs
Breakdown of costs by request direction
## Dashboard Widgets
### Usage Trends
Area chart showing token/cost trends over time with:
* Configurable date ranges: 24H, 7D, 30D, Month, All Time
* Custom date picker for specific periods
* Auto-refresh with "Updated X ago" indicator
* **Daily and hourly granularity** — drill down to per-hour breakdowns
### Cost by Model
Horizontal bar chart breaking down costs per model:
* Claude Opus/Sonnet 4.6 Thinking
* Gemini 3 Pro / Flash variants
* GPT 5.2, GLM 4, Qwen3 Coder
* Color-coded bars for quick comparison
### Model Usage
Donut chart showing distribution of requests across models:
* Percentage breakdown by model
* Visual representation of dominant providers
* **Monthly aggregates** for billing overview
### Session Stats
* **Total Sessions**: Count of coding sessions
* **Avg Cost/Session**: Average spending per session
* **Recent Activity**: List of recent sessions with timestamps
### CLIProxy Stats
Real-time proxy performance metrics:
* **Success Rate**: Percentage with total/failed counts
* **Total Tokens**: Aggregate tokens through proxy
* **Models Used**: Per-model breakdown with request counts
* **Anomaly Detection**: Highlights unusual usage spikes or error rates
### Hourly Breakdown
Available since v7.51.0
Granular per-hour usage view:
* Token and cost breakdown by hour of day
* Identify peak usage patterns
* Useful for rate limit planning
## Time Range Controls
| Range | Description |
| -------- | ------------------------------ |
| 24H | Last 24 hours |
| 7D | Last 7 days (default) |
| 30D | Last 30 days |
| Month | Current calendar month |
| All Time | Complete history |
| Custom | Date picker for specific range |
## API Endpoints
Available since v7.51.0 — programmatic access to analytics data
The CCS dashboard server exposes analytics endpoints at `http://localhost:3000`:
| Endpoint | Method | Description |
| --------------------- | ------ | ---------------------------- |
| `/api/usage/summary` | GET | High-level aggregate totals |
| `/api/usage/daily` | GET | Day-by-day breakdown |
| `/api/usage/hourly` | GET | Hour-by-hour breakdown |
| `/api/usage/models` | GET | Per-model usage and costs |
| `/api/usage/sessions` | GET | Session list with stats |
| `/api/usage/insights` | GET | Anomaly detection results |
| `/api/usage/refresh` | POST | Trigger manual CLIProxy sync |
**Example:**
```bash theme={null}
# Get summary (requires ccs config running)
curl http://localhost:3000/api/usage/summary
# Force refresh CLIProxy data
curl -X POST http://localhost:3000/api/usage/refresh
# Get hourly breakdown
curl http://localhost:3000/api/usage/hourly
```
## Storage
Analytics data is stored locally. No data is sent to external servers.
| Path | Description |
| ----------------------------------------- | ----------------------------------------------- |
| `~/.ccs/usage/` | Local session usage data |
| `~/.ccs/cache/cliproxy-usage/latest.json` | CLIProxy usage snapshot (refreshed every 5 min) |
# Dashboard Authentication
Source: https://docs.ccs.kaitran.ca/features/dashboard/auth
Optional dashboard login with host-setup guidance and remote read-only fallback
# Dashboard Authentication
Protect the CCS dashboard with optional username/password authentication.
Authentication is still disabled by default, but the remote-access behavior is
now much clearer than older CCS releases.
CCS does not ship a default dashboard username or password.
Enable dashboard auth whenever the bind is reachable from another device,
including when you run `ccs config --host 0.0.0.0`.
## Access Modes
| Situation | What users see |
| --------------------------------------------- | --------------------------------------------------------------------------------- |
| Localhost access, auth disabled | Dashboard opens normally without login |
| Remote/IP access, auth disabled | Dashboard UI can open, but sensitive management routes stay localhost-only |
| Remote/IP access, auth enabled but incomplete | Login page shows a setup-state message instead of a misleading blank sign-in form |
| Remote/IP access, auth enabled and configured | Full authenticated dashboard access |
When auth is disabled, remote users can still inspect read-only dashboard
surfaces, but write-capable routes stay locked to localhost until the host owner
runs `ccs config auth setup`.
## Quick Setup
### Recommended Path
```bash theme={null}
ccs config auth setup
ccs config auth show
ccs config
```
The setup wizard:
* prompts for username and password
* hashes the password with bcrypt before saving
* writes the result into `~/.ccs/config.yaml`
* preserves credentials if you later disable auth and want to re-enable it
### Manual Configuration
```yaml theme={null}
dashboard_auth:
enabled: true
username: admin
password_hash: "$2b$10$your-bcrypt-hash-here"
session_timeout_hours: 24
```
```bash theme={null}
export CCS_DASHBOARD_AUTH_ENABLED=true
export CCS_DASHBOARD_USERNAME=admin
export CCS_DASHBOARD_PASSWORD_HASH='$2b$10$your-bcrypt-hash-here'
```
Environment variables override `config.yaml`.
## Login Flow
When authentication is enabled:
1. Open the dashboard URL printed by `ccs config`
2. If auth is configured correctly, CCS redirects you to the login page
3. Enter username and password
4. On success, CCS returns you to the original destination
5. The session persists for the configured timeout (24 hours by default)
The login page also makes the host setup state explicit for remote users,
includes a show/hide password control, and exposes a theme switch before
sign-in.
## Remote Read-Only Fallback
When auth is disabled and the dashboard is reachable beyond localhost:
* remote users can still open read-only dashboard views
* sensitive management routes stay localhost-only
* AI Provider management, CLIProxy auth/status helpers, and other write-capable
endpoints reject non-loopback requests
This means you can inspect the dashboard remotely without silently opening full
management access.
## Configuration Reference
| Key | Type | Default | Description |
| ----------------------- | ------- | ------- | --------------------------------- |
| `enabled` | boolean | `false` | Enable or disable dashboard login |
| `username` | string | `""` | Login username |
| `password_hash` | string | `""` | Bcrypt password hash |
| `session_timeout_hours` | number | `24` | Session lifetime in hours |
## Environment Variables
| Variable | Maps to |
| ----------------------------- | ------------------------------ |
| `CCS_DASHBOARD_AUTH_ENABLED` | `dashboard_auth.enabled` |
| `CCS_DASHBOARD_USERNAME` | `dashboard_auth.username` |
| `CCS_DASHBOARD_PASSWORD_HASH` | `dashboard_auth.password_hash` |
| `CCS_SESSION_SECRET` | Custom session encryption key |
## Security Notes
* CCS uses HTTP-only session cookies instead of `localStorage`
* Login attempts are rate-limited
* Passwords are stored as bcrypt hashes
* Remote write access fails closed when auth is disabled
## Troubleshooting
### Remote users see setup guidance instead of a login form
That means auth is enabled or intended, but the host has not finished
configuration. Run:
```bash theme={null}
ccs config auth setup
```
If you are on the same machine, reopen the localhost dashboard URL instead of
the network URL.
### Remote dashboard is visible but read-only
That is expected when dashboard auth is disabled. Either:
* keep it read-only for lightweight remote inspection, or
* run `ccs config auth setup` on the host to unlock remote changes
### "Too many login attempts"
Rate limiting triggered. Wait 15 minutes or restart the dashboard.
### Session expires unexpectedly
Increase `session_timeout_hours` or check that the session secret is stable
between restarts.
# CCS Bar
Source: https://docs.ccs.kaitran.ca/features/dashboard/ccs-bar
Native macOS menu-bar companion for quota, spend, and account controls
# CCS Bar
CCS Bar is the native macOS menu-bar companion for CCS. It gives you a fast
quota and spend glance without opening the dashboard, then lets you jump into
account controls when you need them.
CCS Bar is macOS-only. It talks to your local CCS server over loopback and
does not call Claude, Codex, or CLIProxy providers directly.
CCS Bar v1 expects the default local CCS data directory at `~/.ccs`. Custom
`CCS_HOME` or `CCS_DIR` layouts may not be discovered by the native app yet.
## Current Snapshot
```bash theme={null}
ccs bar install
```
This downloads `CCS Bar.app` from the `ccs-bar-latest` release into
`~/Applications`, clears the macOS Gatekeeper quarantine, and records how to
start the local server so the app can launch it on its own.
Launch CCS Bar from Spotlight, Finder, or the Dock. The first time you open
the menu, it starts the local CCS server in the background and connects. You
do not need to keep a terminal open.
```bash theme={null}
ccs bar
ccs bar --port 3999
```
`ccs bar` starts the server in the background and returns your prompt right
away, then opens the app. If a server is already running it reuses it. Add
`--port` to choose an exact loopback port.
```bash theme={null}
ccs bar install --launch
ccs bar uninstall
```
## Updating
CCS Bar keeps itself current. When a newer build is published it shows an
**Update available** row at the top of the menu. Click **Update Now** and the app
downloads the new version, replaces itself, and reopens. You never need a
terminal.
Automatic checks are on by default. You can turn them off in **Settings >
Updates** ("Check for CCS Bar updates automatically"). You can also update at any
time from the CLI with `ccs bar install`, which always fetches the latest
published build.
The in-app updater runs `ccs bar install` for you, so keep the CCS CLI on your
PATH and reasonably up to date.
## Commands
| Command | What it does |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| `ccs bar` | Start the background server if needed, then open the app |
| `ccs bar --port ` | Start or move the server to an exact port from 1 to 65535 |
| `ccs bar stop` | Stop the background server |
| `ccs bar status` | Show the process-record, PID, and HTTP reachability state |
| `ccs bar serve` | Run the server in the current terminal (advanced; `ccs bar` runs this for you in the background) |
| `ccs bar install` | Install or update the app |
| `ccs bar uninstall` | Remove the app |
### Port And Lifecycle Behavior
* `--port` accepts only an integer from `1` to `65535`. CCS fails instead of
silently choosing another port when the value is invalid or occupied.
* The selected port is sticky. Later launches try it first, including after
`ccs bar stop`; if it is unavailable, a launch without `--port` can use a
standard fallback port.
* When moving a running server, CCS checks the destination before stopping the
current server. If the replacement cannot start or become ready, CCS tries to
restore the prior server. If restoration also fails, it preserves the prior
discovery and launch files for recovery.
* `ccs bar stop` verifies both the PID and the process start identity before it
sends `SIGTERM`. A mismatch, permission error, signal failure, or timeout
leaves the recovery files untouched instead of risking another process or
losing diagnostic state.
Older CCS versions stored only a number in `server.pid`. Current versions
treat that legacy record as unverifiable: `ccs bar status` reports it as
invalid, and `ccs bar stop` refuses to signal the PID or delete recovery
files. Do not run `kill` against that number alone because macOS may have
reused it. Confirm and quit the CCS server in Activity Monitor, or restart the
Mac; only after confirming it is stopped should you move the stale
`server.pid` and `bar.json` aside and run `ccs bar` again.
## What It Shows
Claude Code and Codex rows show quota windows, reset timing, and the
tightest remaining window first. Codex usage refreshes live, and a refresh
control on the card pulls the latest reading on demand.
A spend chart you can switch between Today, 7-day, and 30-day, with
time-axis labels (hours for today, days for the wider windows). Totals come
from local CCS usage data.
Pause, resume, set default, solo an account, or use tier-lock from the menu.
Open the dashboard, refresh data, change icon style, or open settings
without leaving the menu.
## How It Works
Bugs, confusing states, install problems, and missing provider data.
Workflow ideas, panel layout feedback, and new account actions.
## Troubleshooting
| Symptom | What to try |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Menu shows "CCS is not running" | Open the menu again to let the app start the server, or run `ccs bar status` to check and `ccs bar` to start it |
| Requested port is busy | Choose another free port, or stop the process using that port; CCS leaves an existing Bar server running when the destination preflight fails |
| `server.pid` is invalid after an upgrade | Do not signal the recorded number blindly; follow the legacy PID safety steps above |
| Install says the server predates CCS Bar | Update CCS, restart `ccs bar`, then reinstall |
| macOS blocks first launch | Right-click the app and choose Open, or rerun `ccs bar install` |
| Quota looks stale | Reopen the menu, use the footer refresh, or the refresh control on the Codex card to force a live pull |
| Remote dashboard bind does not work | Keep CCS Bar on loopback; v1 expects `127.0.0.1` |
# Live Auth Monitor
Source: https://docs.ccs.kaitran.ca/features/dashboard/live-auth-monitor
Live provider health, request distribution, and provider drill-downs from the CCS home route
# Live Auth Monitor
The home route now exposes a live provider-health monitor rather than the older
radial-only view. It starts as a provider grid, then drills into one provider
at a time for account-level flow inspection.
## Overview
Access the auth monitor from the dashboard Home page:
```bash theme={null}
ccs config
# View "LIVE Account Monitor" section
```
## Landing View
The default view shows the current request distribution by provider:
* live pulse plus "updated Xs ago" freshness indicator
* summary cards for accounts, success, failed, and success rate
* provider cards with account count, inline success/failure totals, success-rate
bar, and account dots
* click a provider card to open the focused account-flow view
## Provider Drill-Down
Selecting a provider opens the detailed flow view for that provider:
* account-level request flow visualization
* per-account state and request totals
* pause or resume actions without leaving the page
* quota tooltips and provider-specific badges where quota-backed providers
expose them
* back navigation to return to the provider grid
## Status Signals
Use the cards and drill-down together:
* green-biased cards indicate clean request flow
* amber or red signals point to degraded or failed providers
* the monitor keeps selection in local storage, so reopening the dashboard can
return you to the same provider drill-down
The monitor refreshes continuously. When investigation becomes log-heavy, use
the Home route's logs handoff card to jump into `/logs` for request-level
inspection.
## Related
* [Dashboard Overview](/features/dashboard/overview)
* [Dashboard Logs](/features/dashboard/logs)
* [CLIProxy API](/features/proxy/cliproxy-api)
# Dashboard Logs
Source: https://docs.ccs.kaitran.ca/features/dashboard/logs
Structured CCS telemetry stream plus upstream CLIProxy error inspection
# Dashboard Logs
CCS includes a dedicated `System -> Logs` workspace for operational visibility.
It is now a dedicated operations surface with a structured telemetry stream and
an upstream-error compatibility tab.
## Access
```bash theme={null}
ccs config
# Open System -> Logs
# Or navigate directly to /logs inside the current dashboard session
```
## Workspace Layout
The route exposes two tabs:
* **Stream** - CCS-owned structured runtime telemetry
* **Upstream errors** - legacy CLIProxy error files for compatibility
### Stream
The main stream view is a log workspace, not a raw file dump:
* `Live activity` header with live/syncing/disconnected status pill
* entry, trace, and error counters
* desktop 3-pane layout: filters, entry list, detail panel
* mobile detail sheet when you select an entry
* request-aware filters for source, level, module, stage, requestId, time
window, and free-text search
* "hide dashboard internals" filtering for quieter review
* live-tail pause/resume controls with pending-count feedback
### Entry Inspection
Selecting an entry opens a detail panel with:
* **Overview** tab for timestamp, stage, requestId, latency, module, and source
* **Context** tab for structured metadata with redaction-aware reveal controls
* **Raw** tab for copyable JSON
* **Show trace** action when the entry belongs to a correlated request trace
### Upstream Errors
The second tab keeps provider and CLIProxy error files visible without making
them the primary logging model. Use it when you need the old error-log lane or
when only `cliproxy.logging` is enabled.
## Storage Model
### CCS-Owned Structured Logs
Native CCS logs live under:
```text theme={null}
~/.ccs/logs/current.jsonl
~/.ccs/logs/archive/
```
These logs are controlled by the top-level `logging` config block and support:
* minimum log level
* log rotation by size
* archive retention by day count
* context redaction
* a bounded in-memory buffer for dashboard reads
### CLIProxy Runtime Logs
CLIProxy runtime files still live under:
```text theme={null}
~/.ccs/cliproxy/logs/
```
Those files are controlled separately through `cliproxy.logging`.
## Configuration
```yaml theme={null}
logging:
enabled: true
level: info
rotate_mb: 10
retain_days: 7
redact: true
live_buffer_size: 250
```
This is separate from:
```yaml theme={null}
cliproxy:
logging:
enabled: false
request_log: false
```
Use top-level `logging` for CCS-owned runtime events. Use `cliproxy.logging`
only when you need extra CLIProxy runtime files for troubleshooting.
## Operational Notes
* Dashboard `/api/logs` reads are intentionally skipped by request logging so
the log viewer does not recursively log itself.
* The Home route links here through the logs handoff card once you need
request-level inspection.
* Remote users can inspect logs only within the dashboard access rules
currently enforced by dashboard auth and localhost-only fallbacks.
* Redaction is enabled by default so persisted context does not leak obvious
secrets into the log stream.
## Troubleshooting
### The Logs page looks empty
* Check whether top-level `logging.enabled` is still `true`
* Trigger a fresh CCS action, then refresh the page
* If you only enabled `cliproxy.logging`, look in the **Upstream errors** tab
### I only need verbose CLIProxy request traces
Enable `cliproxy.logging.request_log` instead of raising the global CCS logging
level unless you specifically want broader CCS runtime telemetry.
## Related
* [Dashboard Overview](/features/dashboard/overview)
* [CLIProxy API](/features/proxy/cliproxy-api)
* [Configuration Schema](/reference/config-schema)
* [File Locations](/reference/file-locations)
# Dashboard
Source: https://docs.ccs.kaitran.ca/features/dashboard/overview
Current route map and workspace anatomy for the CCS dashboard
# Dashboard
CCS ships a routed dashboard, not a one-screen settings modal. The current UI
in `ccs/cli` `dev` is organized into persistent workspaces with a sidebar, a
header utility bar, and direct routes you can bookmark inside the active
dashboard session.
## Open The Dashboard
```bash theme={null}
ccs config
ccs config --host localhost
ccs config --host 0.0.0.0
```
CCS binds to `localhost` by default, prints the current session URL, and opens
that URL in your browser. When the bind is non-loopback, the dashboard also
surfaces remote-access guidance and auth setup expectations.
## Shell Anatomy
### Sidebar
The left sidebar is grouped into four route clusters:
* **General**: Home and Analytics
* **Identity & Access**: API Profiles, CLIProxy, Copilot, Accounts, Shared Data
* **Compatible CLIs**: Claude Extension, Codex CLI, Factory Droid
* **System**: Health, Logs, Settings
The current Cursor provider flow lives inside **CLIProxy**. The older local
Cursor IDE bridge survives only as a deprecated compatibility surface.
### Header Utilities
The top bar carries live utilities that stay visible across routes:
* connection status
* language switcher
* CCS Bar link for the native macOS menu-bar companion
* docs link
* GitHub link
* privacy toggle
* theme toggle
* authenticated user menu when dashboard auth is enabled
### Global Dialogs
OAuth-driven flows can open project-selection and device-code dialogs above the
current page without changing your route.
## Current Route Map
| Group | Label | Route | Use it for |
| ----------------- | ----------------- | --------------------------- | -------------------------------------------------------------------- |
| General | Home | `/` | landing stats, live account monitor, logs handoff |
| General | Analytics | `/analytics` | usage, cost, and session breakdowns |
| Identity & Access | API Profiles | `/providers` | API and local-model profile CRUD |
| Identity & Access | CLIProxy Overview | `/cliproxy` | OAuth providers, accounts, advanced variants, routing |
| Identity & Access | AI Providers | `/cliproxy/ai-providers` | API-key and connector routes inside CLIProxy |
| Identity & Access | Control Panel | `/cliproxy/control-panel` | embedded upstream CLIProxy management center |
| Identity & Access | GitHub Copilot | `/copilot` | copilot-api install, auth, and daemon status |
| Identity & Access | Cursor Provider | `/cliproxy?provider=cursor` | current Cursor OAuth auth, accounts, and provider config flow |
| Identity & Access | Accounts | `/accounts` | CCS auth profiles and continuity lanes |
| Identity & Access | Shared Data | `/shared` | shared commands, skills, and agents |
| Compatible CLIs | Claude Extension | `/claude-extension` | IDE bindings and apply/reset flows |
| Compatible CLIs | Codex CLI | `/codex` | Codex diagnostics, control center, raw TOML |
| Compatible CLIs | Factory Droid | `/droid` | Droid diagnostics, quick controls, raw JSON |
| System | Health | `/health` | doctor-style system health and grouped checks |
| System | Logs | `/logs` | structured runtime telemetry and legacy errors |
| System | Settings | `/settings` | split-view CCS configuration workspace |
| Deprecated | Cursor IDE Bridge | `/cursor` | legacy local Cursor daemon bridge; use only with `ccs legacy cursor` |
| Direct only | Updates Center | `/updates` | rollout inbox and support-matrix notices |
## Workspace Notes
### Home
The home route is an operational landing page:
* hero counters for profiles, CLIProxy, accounts, and health
* the live auth monitor with provider drill-down
* a dedicated handoff card that moves log inspection into `/logs`
* an embedded error-log monitor under the fold
### Identity And Access
This cluster mixes CCS-native profiles and proxy-driven providers:
* **API Profiles** is the CRUD workspace for settings-based profiles
* **CLIProxy Overview** is the OAuth and variant workspace
* **AI Providers** is the API-key and connector workspace inside CLIProxy
* **GitHub Copilot** remains a dedicated provider page
* **Cursor** now belongs to the CLIProxy provider set; the old Cursor IDE bridge is deprecated compatibility
* **Accounts** is the CCS auth-profile workspace
* **Shared Data** is the asset browser for commands, skills, and agents
That split matters: CCS auth profiles, API profiles, and CLIProxy provider
routes are adjacent in the UI, but they are not the same persistence model.
### Compatible CLIs
The compatible-CLI pages are dedicated control centers, not generic settings
forms:
* [Claude IDE Extension](/features/workflow/claude-extension)
* [Codex Adapter](/features/workflow/codex-adapter)
* [Droid Adapter](/features/workflow/droid-adapter)
### System
The System group now behaves like an operations cluster:
* **Health** mirrors `ccs doctor` status in a rich UI
* **Logs** is the dedicated log operations workspace
* **Settings** is the split-view configuration surface for global CCS config
## Where To Read Next
| If you want to understand... | Read this |
| -------------------------------------------- | ------------------------------------------------------------ |
| account-profile workflows and continuity | [Accounts Workspace](/features/dashboard/accounts-workspace) |
| the split-view config surface | [Settings Workspace](/features/dashboard/settings-workspace) |
| OAuth providers, variants, and routing | [CLIProxy API](/features/proxy/cliproxy-api) |
| API-key and connector routes inside CLIProxy | [AI Providers Workspace](/features/proxy/ai-providers) |
| live auth-state behavior | [Live Auth Monitor](/features/dashboard/live-auth-monitor) |
| log inspection and retention controls | [Dashboard Logs](/features/dashboard/logs) |
# Settings Workspace
Source: https://docs.ccs.kaitran.ca/features/dashboard/settings-workspace
The split-view settings workspace for WebSearch, image analysis, channels, proxy, auth, and backups
# Settings Workspace
The Settings workspace at `/settings` is the dashboard's routed configuration
surface. On desktop it uses a **split view**: form-based controls on the left,
a live read-only snapshot of `~/.ccs/config.yaml` on the right.
## Access
```bash theme={null}
ccs config
# Sidebar -> System -> Settings
# Direct route -> /settings
```
## Current Layout
### Desktop
* **Left panel**: tabbed configuration sections
* **Right panel**: `config.yaml` viewer with copy and refresh actions
* **Resize handle**: lets you rebalance forms vs raw config
### Mobile
The page collapses into a stacked layout. The raw `config.yaml` viewer drops
behind the active section so the forms stay usable on narrow screens.
## Current Tabs
| Tab | What it manages | Related doc |
| ----------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- |
| `WebSearch` | provider readiness, API keys, install hints, and CCS search routing | [WebSearch](/features/ai/websearch) |
| `Image` | MCP-first image analysis state, repair actions, and profile coverage | [Image Analysis](/features/ai/image-analysis) |
| `Channels` | official-channel selection, token status, and launch preview | [CLI Commands](/reference/cli-commands) |
| `Env` | top-level global environment variables saved in CCS config | [Configuration](/getting-started/configuration) |
| `Thinking` | thinking mode, overrides, tier defaults, and provider overrides | [Extended Thinking](/features/ai/extended-thinking) |
| `Browser` | Claude Browser Attach and Codex Browser Tools setup, status, and policy | [Browser Automation](/features/workflow/browser-automation) |
| `Proxy` | local vs remote CLIProxy server settings and connectivity | [Remote Proxy](/features/proxy/remote-proxy) |
| `Auth` | dashboard authentication enablement, secret generation, and status | [Dashboard Authentication](/features/dashboard/auth) |
| `Backups` | backup inventory, restore, and cleanup workflows | [File Locations](/reference/file-locations) |
## Raw Config Pane
The right-hand pane is a **viewer**, not a second editor:
* shows the current `~/.ccs/config.yaml`
* supports copy and refresh actions
* helps you verify what the forms actually persisted
If the file does not exist yet, the workspace points you back to:
```bash theme={null}
ccs migrate
```
## Operational Notes
* Section content is lazy-loaded, so the active tab can recover independently if one section fails
* Structured settings stay in the form controls; raw YAML remains read-only in this workspace
* The page is route-aware, so you can bookmark `/settings` directly inside the current dashboard session
## When To Use This Page
Use the Settings workspace when the change belongs to **shared CCS behavior**:
* search and image-analysis tooling
* announcement and support channels
* global env defaults
* proxy topology
* browser automation exposure policy
* dashboard auth
* backup hygiene
Use the profile workspaces instead when the change is specific to **one
provider or one compatible CLI**.
## Related
* [Dashboard Overview](/features/dashboard/overview)
* [WebSearch](/features/ai/websearch)
* [Image Analysis](/features/ai/image-analysis)
* [Remote Proxy](/features/proxy/remote-proxy)
# Account Pools
Source: https://docs.ccs.kaitran.ca/features/pool
Run several Claude accounts as one pool and auto-continue when an account hits its limit
# Account Pools
An account pool lets you put several Claude accounts behind one provider profile
so a session keeps going when one account hits its rate limit. Instead of seeing
a limit error and switching accounts by hand, the pool moves the conversation to
the next available account for you.
A pool is three things working together:
1. **Several accounts** authenticated under the built-in `claude` CLIProxy
provider.
2. **One provider profile** you launch with `ccs claude`.
3. **Auto-continue on limit**: when the active account is rate limited, CLIProxy
hops to the next account in the pool so the turn completes.
Account pools route through your local CLIProxy. They are separate from native
account profiles (`ccs work`, `ccs personal`). The two systems do not share
session history. See [When not to pool](#when-not-to-pool) and
[Migrating from native profiles](#migrating-from-native-profiles).
## Terminology
These words get mixed up. Here is what each one means in CCS.
| Term | Meaning |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account profile** | A native Claude account lane created with `ccs auth create `, run with `ccs `. Has its own `CLAUDE_CONFIG_DIR` and its own session history. Does **not** pool. |
| **OAuth account** | A single Claude login (one email, one set of tokens). The unit a pool is built from. |
| **Variant** | A user-defined CLIProxy provider entry under `config.cliproxy.variants` (for example, a custom Codex model variant). |
| **Provider** | A CLIProxy backend such as `claude`, `agy`, `gemini`, or `codex`. A pool lives under one provider. |
| **Pool** | Two or more OAuth accounts under one CLIProxy provider with pool routing enabled. Auto-continues on limit. |
### Codex has two separate lanes
Codex can confuse you the same way, because the word "pool" shows up in two
different places:
* **CLIProxy Codex pool**: OAuth accounts under the `codex` CLIProxy provider,
reached with `ccs codex`. This is the pool world described on this page.
* **Native Codex runtime lane**: the `ccsx`, `ccsxp`, and `ccsd` aliases route a
profile to the native Codex CLI. That is a runtime target, not a CLIProxy
account pool. See [Codex Adapter](/features/workflow/codex-adapter).
Same two-worlds split as Claude (CLIProxy lane vs native lane), different
provider. When you read "Codex pool" make sure you know which lane is meant.
## Set up a pool in three commands
```bash theme={null}
ccs claude --auth
```
Opens your browser for Claude OAuth. The token is stored under the built-in
`claude` CLIProxy provider.
```bash theme={null}
ccs claude --auth --add
```
Run this once per extra account. Each `--add` opens a fresh OAuth flow and
stores the new account alongside the first. For a three-account pool, run it
twice.
When you cross from one account to two, CCS offers to turn on pool routing
for you (interactive terminals only). You can accept there, or enable it
later with `ccs cliproxy pool --enable`.
```bash theme={null}
ccs claude
```
`ccs claude` runs Claude Code through the local CLIProxy with all your
authenticated accounts behind it. When one account is rate limited, the pool
continues on the next one.
To confirm pool routing is on:
```bash theme={null}
ccs cliproxy pool
```
## How failover behaves
### Fill-first plus session affinity
Pool routing uses two settings together:
* **fill-first**: drain one account fully before moving to the next, instead of
spreading requests evenly. This keeps as much of your conversation as possible
on a single account.
* **session affinity**: pin one conversation to one account (TTL 1h) so a
multi-turn session stays put until it has to move.
The result: your conversation sticks to one account until that account hits its
limit, then hops.
### A pre-stream limit hops transparently
When the active account is rate limited **before** the response starts
streaming, CLIProxy switches to the next account and the turn completes there.
You do not see an error. The hop is transparent.
### The turn right after a hop is slower
Here is the cost to know about. When the pool hops to a new account, the new
account has none of your conversation cached. The next turn re-processes your
**whole** conversation from the start on the new account.
That means the turn right after a hop is noticeably slower, and the slowdown is
proportional to how large your conversation is. A short conversation re-processes
quickly. A long one (tens of thousands of tokens of context) takes longer,
because the entire context has to be read again on the fresh account.
CCS does not publish a fixed latency number here because it depends on context
size, model load, and provider response time. Treat the first turn after a hop
as a full-context turn, not a warm-cache turn.
This happens once per hop. After the hop, the conversation is cached on the new
account again and turns return to normal speed until the next hop.
## When not to pool
A pool is the right tool when you want one continuous session that survives rate
limits. It is the wrong tool when you want accounts kept apart.
**If you want strict separation between accounts** (work vs personal, separate
billing, separate history), use native account profiles instead:
```bash theme={null}
ccs auth create work
ccs auth create personal
ccs work "review this PR"
ccs personal "help with a side project"
```
Native profiles keep credentials, tokens, and session history isolated per
account. They do not auto-continue across accounts. See
[Claude Accounts](/providers/concepts/claude-accounts).
**Bare `ccs` does not pool.** Running plain `ccs` launches your native default
account lane, not the CLIProxy pool. Pooling only happens when you launch through
`ccs claude` with pool routing enabled. If you want pooled failover, use
`ccs claude`; if you want your single native account, use `ccs`.
## Leaving a pool
To turn pool routing off, use the disable command. Do not hand-edit routing back
to plain round-robin (see the warning below).
```bash theme={null}
ccs cliproxy pool --disable
```
This regenerates the CLIProxy config with cooling disabled (stability mode) and
restores your original routing settings. The exact output:
```
[OK] Pool routing disabled. CLIProxy config regenerated with cooling disabled (stability mode).
Your original routing settings are restored.
If you have multiple accounts and want fair distribution, round-robin is active.
To avoid cache-burn with large multi-account fleets, consider reducing to 1 account
or re-enabling pool routing: ccs cliproxy pool --enable
```
### Why not just switch to round-robin
It is tempting to "leave the pool" by setting routing to plain round-robin with
no session affinity. Do not do this with a multi-account fleet.
Round-robin with no affinity spreads each request across accounts. Without
affinity, consecutive turns of the same conversation land on different accounts,
and each landing re-processes your whole conversation on a cold account. That is
the cache-burn footgun: you pay the full context-recompute cost on most turns,
not just on a hop.
`ccs cliproxy pool --disable` avoids this. It restores a safe non-pool config
(cooling disabled, your original routing), instead of leaving you in the
worst-case round-robin-no-affinity state.
## Migrating from native profiles
If you already run native account profiles (`ccs work`, `ccs personal`) and want
to pool those same accounts, read this first. The two lanes do not share
credentials or history.
### You re-authenticate each account fresh
You cannot import credentials from a native profile into the pool. A native
profile's refresh token is bound to a different OAuth client, so the pool cannot
reuse it. To pool an account you already use natively, authenticate it again
under the `claude` CLIProxy provider:
```bash theme={null}
ccs claude --auth # first account, fresh OAuth
ccs claude --auth --add # each additional account, fresh OAuth
```
Same Claude login, new OAuth grant. This is required, not optional.
### Session history does not follow
Pooled sessions live in the CLIProxy lane. Your native profile's session history
and your `--continue` / resume inventory stay in the native lane. They do **not**
move into the pool. After migrating, a pooled `ccs claude` session starts with a
clean history; your old `ccs work` transcripts remain reachable only through
`ccs work`.
### Pause the native profile for the same account
Once an account is in the pool, do not keep launching the same account through
its native profile at the same time. Running one Claude account in two lanes
concurrently (native profile in one terminal, pool in another) is the one
behavior that raises account risk. See [Safety notes](#safety-notes).
To avoid it, pick one lane per account. If you migrate an account into the pool,
stop using its native profile for live sessions, or remove the native profile so
there is no second lane to launch by accident.
## Caveats
Read these before you rely on a pool.
### Mid-stream errors do not re-route
The transparent hop only applies when a limit is hit **before** the response
starts streaming. If an account fails **after** the first chunks have already
streamed, that turn is not re-routed: you see a visible error for that turn. The
pool hops on the **next** turn, not retroactively.
The exact visible error text can vary by Claude Code version and provider
response, so the important rule is timing: after chunks start streaming, CCS
cannot rewind and replay that same turn on a different account.
### All accounts cooling vs a paused account
These are two different failure states with two different errors:
* **All accounts cooling**: every account in the pool is rate limited at once.
You get a 429 with a reset time telling you when the soonest account frees up.
* **A paused account**: the only candidate is paused (for example, after a ban
pattern auto-pause), which surfaces as a different error, not a 429-with-reset.
Use `ccs cliproxy quota` to tell them apart. Cooling accounts show
`cooling until ` when CCS can see a reset time; paused accounts show
`paused (manual or safety)` and include a resume hint.
### One context recompute per hop
Every hop pays one full context recompute on the new account, which costs both
quota (the re-read tokens) and latency (the slower turn described in
[How failover behaves](#the-turn-right-after-a-hop-is-slower)). Pools minimize
hops with fill-first plus affinity, but a hop is never free.
### Remote and Docker pools need manual config
On a remote or Docker CLIProxy, CCS cannot manage the pool the same way it does
locally:
* The interactive opt-in prompt is not shown.
* Session affinity is not remotely toggleable from CCS.
* You must configure pool routing in the remote CLIProxy `config.yaml` by hand.
If you run multiple accounts on a remote CLIProxy **without** pool config, you
get round-robin with no affinity, which is the cache-burn state described under
[Leaving a pool](#why-not-just-switch-to-round-robin). To enable pool routing
manually on a remote target, add to the CLIProxy `config.yaml`:
```yaml theme={null}
disable-cooling: false
max-retry-credentials: 3
routing:
strategy: fill-first
session-affinity: true
session-affinity-ttl: "1h"
```
### Claude quota percentages are limited
Claude OAuth does not expose full quota percentages to CCS the way some other
providers do (the underlying signal is `policy_quota_unsupported`). You will see
limit and reset behavior, but not a precise "N% remaining" figure for Claude
pool accounts.
### Claude tier detection is unavailable
CCS cannot detect the subscription tier (Pro vs Max) of a Claude pool account.
Tier-based drain ordering (`--by-tier`) is available for providers that report
tier (`agy`, `gemini`), but not for `claude`. For Claude, the pool drains in
file order, or in an order you set manually with
`ccs cliproxy accounts order claude --set`.
## Safety notes
Pool routing ships with guardrails on by default:
* **Cooldowns are honored.** A rate-limited (429) account is suspended briefly
with exponential backoff (1s up to 30m). A broken-auth account (401/403) is
suspended for 30 minutes, because broken auth should not keep taking traffic.
* **Retry cap.** A single request stops after `max-retry-credentials: 3`
attempts across accounts instead of walking the entire fleet.
* **Ban-pattern auto-pause.** If an account shows a ban signal, CCS pauses it out
of rotation automatically.
### The honest version of account risk
Pools do **not** add a new ban vector. Running accounts behind one local CLIProxy
is the same traffic shape Anthropic already sees from a single client.
The risk that **does** exist is concurrency: the same Claude account active in
two clients or two lanes at once. A pool by itself does not create this, because
the pool drains one account at a time with affinity. But **migration can create
it** if you keep an active native profile for an account you have also added to
the pool. Then you can launch that one account twice (native lane plus pool lane)
and run it concurrently.
The fix is in [Migrating from native profiles](#pause-the-native-profile-for-the-same-account):
pick one lane per account. Pool the account, or run it natively, but not both at
the same time.
## Related commands
| Command | What it does |
| ------------------------------------------------ | ----------------------------------------------------------------- |
| `ccs cliproxy pool` | Show pool routing status |
| `ccs cliproxy pool --enable` | Enable pool routing (fill-first, affinity, cooling on, retry cap) |
| `ccs cliproxy pool --disable` | Disable pool routing and restore a safe non-pool config |
| `ccs cliproxy accounts order claude` | Show the order accounts drain in |
| `ccs cliproxy accounts order claude --set ` | Set a manual drain order |
See the [CLI reference](/reference/cli-commands#cliproxy-management) for the full
command surface.
## Next steps
Native account profiles when you want accounts kept separate
OAuth, multi-account, and quota details for the claude provider
Step-by-step account setup across providers
Full pool, routing, and account command surface
# AI Providers Workspace
Source: https://docs.ccs.kaitran.ca/features/proxy/ai-providers
Configure API-key and connector-based upstream routes inside the CLIProxy dashboard
# AI Providers Workspace
The AI Providers workspace at `/cliproxy/ai-providers` is the dashboard surface
for **API-key and connector-based upstream routes inside CLIProxy**. It is the
place to manage non-OAuth provider families that still belong to the proxy
layer.
## Access
```bash theme={null}
ccs config
# Sidebar -> CLIProxy -> AI Providers
# Direct route -> /cliproxy/ai-providers
```
## Source Modes
The page always shows where it is reading and writing provider definitions:
| Mode | What it means |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `Local CLIProxy` | entries come from the local CLIProxy config and are written back into the local top-level YAML sections |
| `Remote CLIProxy` | entries are managed through the remote proxy's management API using the configured management auth |
## Provider Families
| Family | Route path | Typical use |
| ----------------- | ----------------------------- | ----------------------------------------------------------------------- |
| Gemini | `/api/provider/gemini` | Google Gemini API keys plus optional route defaults |
| Codex | `/api/provider/codex` | OpenAI or Codex API keys and endpoint overrides |
| Claude | `/api/provider/claude` | Anthropic-compatible routes, aliases, and filters |
| Vertex | `/api/provider/vertex` | Vertex AI keys and regional endpoint overrides |
| OpenAI-Compatible | `/api/provider/openai-compat` | named connectors for OpenRouter, Together, and custom OpenAI-style APIs |
## Workspace Layout
### Family Rail
The family rail shows readiness at a glance:
* **Ready** means all required secrets are present
* **Needs attention** means the family has entries but at least one is incomplete
* **Empty** means no saved entries yet
### Saved Entries
After choosing a family, the middle list shows the saved entry or entries for
that family, including routing mode and whether secrets are configured.
### Editor
The editor is split into two views:
* **Config / Usage** for guided fields and routing explanations
* **Raw JSON / Preview** for the payload and resulting environment snapshot
The preview includes a global-env indicator so you can see what the connector
would inject before saving it.
## Routing Modes
Entries can stay minimal or become more advanced:
| Mode | Trigger | Use it when |
| --------------- | ------------------ | ---------------------------------------------------------------------- |
| Default runtime | no override fields | the provider family default is already correct |
| Direct upstream | `base-url` only | you want the route to hit a specific upstream endpoint |
| Prefixed route | `prefix` set | requested model names need a stable prefix rewrite |
| Proxy override | `proxy-url` set | traffic should pass through another proxy before reaching the upstream |
Headers, excluded models, and explicit model aliases are available for edge
cases, but they are not the minimum working setup.
## API Profiles Vs AI Providers
Use the AI Providers workspace when the route should stay **inside CLIProxy**.
Use [API Profiles](/providers/concepts/api-profiles) when you want a
**CCS-native profile** with its own `.settings.json`, presets, and direct
runtime selection.
## Related
* [CLIProxy API](/features/proxy/cliproxy-api)
* [API Profiles](/providers/concepts/api-profiles)
* [Remote Proxy](/features/proxy/remote-proxy)
# CLIProxy API
Source: https://docs.ccs.kaitran.ca/features/proxy/cliproxy-api
The routed CLIProxy workspace for OAuth providers, variants, routing, and upstream management
# CLIProxy API Integration
CCS uses [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) by
default, with an opt-in
[CLIProxyAPIPlus community fork](https://github.com/kaitranntt/CLIProxyAPIPlus)
for plus-only providers. In the current CCS UI, that capability is split
across **three routes**, not one generic page.
## Current Surface Map
| Route | What lives there | Use it when |
| ------------------------- | ------------------------ | ---------------------------------------------------------------------- |
| `/cliproxy` | OAuth overview workspace | provider status, accounts, advanced variants, routing, account actions |
| `/cliproxy/ai-providers` | AI Providers workspace | API-key and connector routes that belong inside CLIProxy |
| `/cliproxy/control-panel` | embedded control panel | upstream management-center features that CCS does not re-skin |
## OAuth Overview Workspace
The `/cliproxy` route is the main CCS-owned control surface. It includes:
* a provider rail for authenticated OAuth providers
* a variant list for CCS-managed provider variants
* a proxy status widget and backend label
* `Add Account` as the primary account connection flow
* `Advanced Variant` for separate runtime/profile variants
* provider editors for accounts, models, targets, and routing
* deep links such as `?provider=claude` and `?action=auth` for focused flows
## Supported OAuth Providers
| Provider | Status | Notes |
| --------------------------- | ----------- | ------------------------------------------------------- |
| Claude | OAuth | Anthropic Claude with quota support |
| Gemini | OAuth | Google Gemini via OAuth |
| Codex | OAuth | OpenAI Codex routing |
| xAI (Grok) | OAuth | device-code OAuth; canonical ID `xai`, CLI alias `grok` |
| Antigravity | OAuth | multi-account routing |
| GitHub Copilot (deprecated) | OAuth | Compatibility account routing with quota support |
| Kiro | OAuth | AWS Builder ID / IDC-driven Kiro access |
| iFlow | OAuth | alternative AI routing |
| Kimi | OAuth | Moonshot Kimi OAuth-backed routing |
| Cursor | OAuth | browser-driven polling flow via CLIProxy |
| GitLab Duo | OAuth / PAT | browser OAuth or PAT login on the same shortcut |
| CodeBuddy | OAuth | browser-driven polling flow via CLIProxy |
| Kilo AI | OAuth | device-code flow through CLIProxy |
| Qoder | OAuth | device-code flow through CLIProxy |
### Quota-Supported Providers
`agy` · `claude` · `codex` · `gemini`
Deprecated compatibility provider: `ghcp`
### Backend Requirements
CCS registers **15 CLIProxy providers** today; **14** support account linking.
Qwen is the exception because the bundled runtime does not expose Qwen OAuth
account linking. Not every linkable provider works on both backend binaries.
* `original` is the default backend and tracks `router-for-me/CLIProxyAPI`
* `plus` downloads the maintained `kaitranntt/CLIProxyAPIPlus` fork and
migrates legacy deleted-upstream Plus installs safely to the original backend
* The embedded control panel follows the backend: `original` uses upstream
CPAMC, while `plus` uses the maintained
`kaitranntt/Cli-Proxy-API-Management-Center` dashboard fork
* Works on `original` or `plus`: `agy`, `claude`, `codex`, `gemini`, `iflow`,
`kimi`, `xai`
* Requires `plus`: `codebuddy`, `cursor`, `gitlab`, deprecated `ghcp`
compatibility, `kilo`, `kiro`, and `qoder`
Available since v7.48.0
Sync only processes profiles with `target: claude` (or no target, which defaults to `claude`). Profiles with `target: droid` are excluded because Droid uses a different configuration format (`~/.factory/settings.json`).
This means:
* API profiles with `target: droid` are **not** synced to CLIProxy config
* CLIProxy variants with `target: droid` are still managed but their settings path differs
* Use the [Droid dashboard page](/features/workflow/droid-adapter#dashboard-droid-page) to manage Droid-targeted profiles
## Dashboard Integration
### Sync Status Card
Dashboard shows real-time sync status:
**Location:** Settings → CLIProxy Sync
**Displays:**
* Auto-sync enabled/disabled
* Watcher status (running/stopped)
* Syncable profile count
* Last sync timestamp
**Actions:**
* Toggle auto-sync
* Manual sync trigger
* View profile list
### Profile Management
Profiles managed via Dashboard are automatically synced:
1. Go to Dashboard → API Profiles
2. Add/edit GLM, Kimi for Coding, or custom profile
3. Auto-sync triggers within 3 seconds
4. Profile available via `ccs -`
## Troubleshooting
### Auto-Sync Not Working
**Check watcher status:**
```bash theme={null}
ccs cliproxy sync
# → Shows "Watcher: Running" or "Watcher: Stopped"
```
**Common issues:**
* Auto-sync disabled → Enable in `~/.ccs/config.yaml` (`cliproxy.auto_sync: true`)
* Watcher crashed → Restart Dashboard or run `ccs cliproxy sync`
* Invalid profile → Check `settings.json` for syntax errors
### Profile Not Syncing
**Verify profile is syncable:**
```bash theme={null}
ccs cliproxy sync
# → Lists "Syncable Profiles"
```
**Profile missing from list means:**
* API key placeholder not replaced
* `ANTHROPIC_AUTH_TOKEN` missing from `settings.json`
* Profile name contains invalid characters
**Fix:**
```bash theme={null}
# Reconfigure profile
ccs api create glm
# → Enter real API key (not placeholder)
```
### Manual Sync Fails
**Error:** "Failed to sync: ``"
**Solutions:**
```bash theme={null}
# Check CLIProxy config permissions
ls -la ~/.ccs/cliproxy/config.yaml
# Ensure CLIProxy directory exists
mkdir -p ~/.ccs/cliproxy
# Trigger sync
ccs cliproxy sync
```
## Remote Proxy Sync
For remote CLIProxy deployments, sync profiles to remote server.
**Coming Soon:** Remote sync via Management API
**Current Workaround:**
1. Sync locally: `ccs cliproxy sync`
2. Copy `~/.ccs/cliproxy/config.yaml` to remote server
3. Restart remote CLIProxy instance
## Security Considerations
**API Key Storage:**
* Keys stored in `~/.ccs/*.settings.json` (plain text)
* Synced to `~/.ccs/cliproxy/config.yaml` (plain text)
* File permissions: `600` (owner read/write only)
**Best Practices:**
* Never commit `*.settings.json` or `config.yaml` to git
* Use environment variables for sensitive keys
* Rotate API keys regularly
* Encrypt home directory on shared machines
## Hybrid Model Catalog Sync
Available since v7.39.0
CCS automatically syncs remote model catalogs from CLIProxyAPI and keeps static fallback catalogs for times when no usable live or cached catalog is available.
### Overview
Catalog sync prefers a live CLIProxy management catalog, then an unexpired local cache, then the bundled static catalog. Static metadata can enrich matching live models, but static-only models are not re-added to a successful live catalog.
**Syncable Providers:**
* `agy` (Antigravity)
* `claude` (Claude via CLIProxy)
* `codex` (OpenAI Codex)
* `gemini` (Google Gemini)
* `iflow` (iFlow)
* `kimi` (Moonshot Kimi)
* `kiro` (Kiro)
* `qoder` (Qoder)
* `qwen` (Qwen; catalog only, no bundled account linking)
* `xai` (xAI Grok)
* `ghcp` (deprecated GitHub Copilot compatibility)
### How It Works
**Live Catalog Behavior:**
1. Live models are authoritative when available.
2. Matching static metadata is overlaid where the live definition omits it.
3. Models present only in the live catalog are added.
4. Static-only models are not re-added to a successful live catalog.
5. The complete static catalog is used only when neither live data nor an
unexpired cache is usable.
**Cache:**
* Location: `~/.ccs/model-catalog-cache.json`
* TTL: 24 hours
* Auto-refresh on cache expiry
### CLI Commands
```bash theme={null}
# View current catalog cache status
ccs cliproxy catalog
# Force refresh from remote
ccs cliproxy catalog refresh
# Reset to static catalog (clear cache)
ccs cliproxy catalog reset
```
### Dashboard Integration
Dashboard fetches synced catalog via `/api/cliproxy/catalog` endpoint. Model selection dropdowns automatically show latest available models.
### Troubleshooting
**Catalog out of date:**
```bash theme={null}
# Force refresh
ccs cliproxy catalog refresh
```
**Remote fetch fails:**
* Uses an unexpired cache when one exists; otherwise uses the static catalog
* A failed refresh does not delete the cache file, but an expired cache is ignored
* The 24-hour value is the cache TTL, not a refresh retry interval
**Clear corrupted cache:**
```bash theme={null}
ccs cliproxy catalog reset
```
***
## Related
* [CLIProxy API](/features/proxy/cliproxy-api) - OAuth provider integration
* [API Profiles](/providers/concepts/api-profiles) - Profile configuration
* [Dashboard](/features/dashboard/overview) - Visual management
* [CLI Commands](/reference/cli-commands) - Full command reference
# Copilot API (Deprecated)
Source: https://docs.ccs.kaitran.ca/features/proxy/copilot-api
Deprecated GitHub Copilot compatibility integration for Claude Code
# Copilot API Integration (Deprecated)
CCS keeps [copilot-api](https://github.com/ericc-ch/copilot-api) integration
available for existing local GitHub Copilot setups. This is now deprecated
compatibility, not a recommended path for new provider setup.
GitHub usage-based Copilot billing begins June 1, 2026. Prefer Codex or another
active provider for new work.
## Overview
**Unofficial API - Use at Your Own Risk**
* Reverse-engineered API - may break anytime
* Excessive use may trigger account restrictions
* No warranty, no responsibility from CCS
## Setup
### 1. Install copilot-api
```bash theme={null}
ccs config
# Navigate to GitHub Copilot → Install copilot-api
```
### 2. Start Daemon
The Copilot proxy runs as a local daemon on port 4141:
* **Status**: Stopped/Running indicator
* **Port**: 4141 (configurable)
* **Start/Stop**: Control buttons in dashboard
## Model Tiers
### Free Tier
No premium usage count - unlimited access:
| Model | Description |
| --------------------- | ---------------- |
| **GPT-4.1 (Free)** | General purpose |
| **GPT-5 Mini (Free)** | Faster responses |
### Pro+ Required
Uses premium request quota from your subscription:
| Model | Description |
| --------------------- | -------------------- |
| **Claude Opus 4.5** | Complex reasoning |
| **Claude Sonnet 4.5** | Balanced performance |
| **GPT-5.2** | Latest GPT model |
| **GPT-5.1 Codex Max** | Code-optimized |
| **Gemini 2.5 Pro** | Google's flagship |
## Model Mapping
Configure which models handle each tier:
| Tier | Description | Default |
| ----------------- | ----------------- | ------- |
| **Default Model** | No tier specified | gpt-4.1 |
| **Opus** | Complex reasoning | gpt-4.1 |
| **Sonnet** | Balanced | gpt-4.1 |
| **Haiku** | Fast responses | gpt-4.1 |
## Raw Configuration
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:4141",
"ANTHROPIC_AUTH_TOKEN": "",
"ANTHROPIC_MODEL": "gpt-4.1",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-4.1",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-4.1",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-4.1"
}
}
```
## Requirements
Active subscription (Individual, Business, or Enterprise)
`gh` CLI authenticated with your GitHub account
copilot-api is an open-source project. See
[GitHub](https://github.com/ericc-ch/copilot-api) for implementation details.
# OpenAI-Compatible Provider Routing
Source: https://docs.ccs.kaitran.ca/features/proxy/openai-compatible-providers
Run Claude Code through CCS API profiles backed by OpenAI-compatible chat completions endpoints
# OpenAI-Compatible Provider Routing
CCS can bridge Claude Code into OpenAI-compatible providers through a local
Anthropic-compatible proxy. This is useful for Hugging Face Inference
Providers, OpenRouter, Ollama, llama.cpp, OpenAI-compatible self-hosted
gateways, and similar APIs.
## Quick Start
Create an API profile, then launch it normally:
```bash theme={null}
ccs api create --preset hf
ccs hf
```
For Claude-target launches, CCS detects compatible OpenAI-style endpoints,
starts a local proxy on `127.0.0.1`, translates Anthropic `/v1/messages`
requests into OpenAI chat-completions requests, and translates streaming
responses back into Anthropic SSE.
## Manual Proxy Lifecycle
Use the `ccs proxy` command when you want to start, inspect, activate, or stop
the local proxy explicitly:
```bash theme={null}
ccs proxy start hf
eval "$(ccs proxy activate hf)"
ccs proxy status hf
ccs proxy stop hf
```
Useful variants:
```bash theme={null}
ccs proxy start hf --host 127.0.0.1
ccs proxy start hf --port 3460
ccs proxy activate --fish
```
`ccs proxy activate` prints the local runtime contract for the selected
profile, including `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, model
defaults, timeout settings, telemetry suppression, and `NO_PROXY`.
## Adaptive Ports
CCS stores local proxy state per profile, so multiple compatible profiles can
run at the same time.
Port selection precedence:
1. CLI `--port`
2. `proxy.profile_ports[profile]`
3. shared preferred `proxy.port`
4. adaptive per-profile fallback
Legacy shared `proxy.port: 3456` values are treated as unset so older configs
move onto adaptive ports instead of staying on the hot legacy default. Pin
`3456` explicitly with `--port` or `proxy.profile_ports` only if you really need
that exact binding.
```yaml theme={null}
proxy:
port: 45000
profile_ports:
hf: 3460
openrouter: 3461
```
## Request-Time Routing
The proxy can route a request to another compatible profile or model at request
time:
| Selector | Example | Behavior |
| --------------- | ---------------------------- | ------------------------------------ |
| `profile:model` | `deepseek:deepseek-reasoner` | route to exact profile and model |
| `profile` | `openrouter` | route to that profile default |
| plain model id | `deepseek-chat` | match configured model slots exactly |
Scenario routing is configured under `proxy.routing`:
```yaml theme={null}
proxy:
routing:
default: "deepseek:deepseek-chat"
background: "ollama:qwen2.5-coder:0.5b"
think: "deepseek:deepseek-reasoner"
longContext: "openrouter:google/gemini-2.5-pro"
longContextThreshold: 60000
webSearch: "openrouter:perplexity/sonar-pro"
```
Current scenarios detect background models, thinking-enabled requests,
long-context requests, and web-search tool usage.
## Anthropic Passthrough Profiles
Most compatible profiles translate Claude Code's Anthropic `/v1/messages`
requests into OpenAI `/chat/completions` requests before forwarding upstream.
Some coding endpoints, including Kimi for Coding, already expect Anthropic
message payloads and reject OpenAI-formatted chat-completions requests.
For those profiles, CCS uses passthrough mode. It forwards the original
Anthropic request body to the upstream `/v1/messages` endpoint and preserves the
incoming coding-agent `User-Agent` header when present.
Passthrough is automatic for known Anthropic-style hosts such as
`api.kimi.com` and `api.anthropic.com`. For another gateway that expects
Anthropic `/v1/messages`, set this env key in the profile:
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://gateway.example.com",
"ANTHROPIC_AUTH_TOKEN": "sk-...",
"ANTHROPIC_MODEL": "provider-model",
"CCS_DROID_PROVIDER": "generic-chat-completion-api",
"CCS_OPENAI_PROXY_PASSTHROUGH": "1"
}
}
```
Use passthrough only for Anthropic-compatible message endpoints. Leave it unset
for normal OpenAI-compatible chat-completions providers.
## Reasoning Model Payloads
OpenAI GPT-5 and o-series chat-completions models reject `max_tokens` and expect
`max_completion_tokens` instead. CCS automatically reshapes payloads for known
public model names such as `gpt-5.4`, `openai/gpt-5.4`, and `o3`.
If your OpenAI-compatible gateway exposes a reasoning model through an opaque
deployment ID, CCS cannot infer that from the model string. Add this env key to
that profile's settings:
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://gateway.example.com/v1",
"ANTHROPIC_AUTH_TOKEN": "sk-...",
"ANTHROPIC_MODEL": "deployment-id",
"CCS_DROID_PROVIDER": "generic-chat-completion-api",
"CCS_OPENAI_REASONING_MODEL": "1"
}
}
```
With this opt-in, CCS renames `max_tokens` to `max_completion_tokens` and strips
OpenAI-incompatible metadata from the upstream chat-completions request. Leave it
unset for generic gateways whose models still require `max_tokens`.
## Related Project
[claude-code-router](https://github.com/musistudio/claude-code-router) is a
standalone router whose transformer architecture informed this CCS flow. Use
CCR when you want a standalone router. Use CCS when you want routing integrated
with CCS profiles, runtime bridges, and the `ccs` command surface.
## Related
* [API Profiles](/providers/concepts/api-profiles)
* [CLI Commands](/reference/cli-commands#local-openai-compatible-proxy)
* [Configuration Schema](/reference/config-schema#openai-compatible-local-proxy-configuration)
# OpenRouter Integration
Source: https://docs.ccs.kaitran.ca/features/proxy/openrouter
Access 300+ AI models through OpenRouter's unified API
# OpenRouter Integration
CCS v7.0.0 introduces OpenRouter as a first-class provider. Access 300+ AI models through a unified API with intelligent model selection and tier mapping.
## Overview
## Key Features
Access Claude, GPT, Gemini, Llama, and more through one API
Visual model selection with search and filtering in CLI and UI
Automatic opus/sonnet/haiku tier assignment for model routing
Real-time detection of newest models from OpenRouter catalog
## Quick Start
### Via CLI
```bash theme={null}
ccs api create --preset openrouter
```
The CLI launches an interactive model picker:
1. Enter your OpenRouter API key
2. Browse or search available models
3. Select models for each tier (opus, sonnet, haiku)
4. Profile is created and ready to use
### Via Dashboard
```bash theme={null}
ccs config
```
Click "API Profiles" in the sidebar (note the OpenRouter badge).
Click "Create Profile" and select "OpenRouter" from Provider Presets.
Use the model picker to select models for each tier.
## Model Tier Mapping
CCS maps OpenRouter models to Claude Code's tier system for intelligent model routing:
| Tier | Purpose | Recommended Models |
| ---------- | ------------------------------- | ----------------------------- |
| **Opus** | Complex reasoning, architecture | Claude 3.5 Opus, GPT-4o |
| **Sonnet** | General coding, balanced | Claude 3.5 Sonnet, Gemini Pro |
| **Haiku** | Quick tasks, cost-efficient | Claude 3 Haiku, GPT-4o-mini |
### Exacto Models
CCS prioritizes **Exacto-tuned models** for agentic performance. These models are optimized for:
* Tool calling accuracy
* Code generation quality
* Instruction following
Look for models tagged with "Exacto" in the picker for best results with Claude Code workflows.
## Configuration
### Profile Structure
OpenRouter profiles use the standard CCS settings format:
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_AUTH_TOKEN": "sk-or-v1-xxxxx",
"ANTHROPIC_MODEL": "anthropic/claude-3.5-sonnet",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-3-opus",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-3-haiku"
}
}
```
### Environment Variables
| Variable | Description |
| ------------------------------- | ----------------------------------- |
| `ANTHROPIC_BASE_URL` | Must be `https://openrouter.ai/api` |
| `ANTHROPIC_AUTH_TOKEN` | Your OpenRouter API key |
| `ANTHROPIC_MODEL` | Default model (sonnet tier) |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Model for opus tier |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Model for haiku tier |
## Usage
```bash theme={null}
# Use OpenRouter profile
ccs openrouter "implement the authentication service"
# Parallel workflows
ccs openrouter "design the system" # Terminal 1: Architecture
ccs glm "implement the service" # Terminal 2: Bulk coding
```
## Model Selection Tips
* **anthropic/claude-3.5-sonnet** - Excellent tool use
* **openai/gpt-4o** - Strong reasoning
* Models with "Exacto" tag - Optimized for agents
* **anthropic/claude-3-haiku** - Fast and cheap
* **openai/gpt-4o-mini** - Good balance
* **meta-llama/llama-3.1-8b-instruct** - Open source
* **anthropic/claude-3.5-sonnet** - 200K context
* **google/gemini-pro-1.5** - 1M context
* **anthropic/claude-3-opus** - 200K context
## Troubleshooting
Verify your key at [openrouter.ai/keys](https://openrouter.ai/keys):
```bash theme={null}
curl -H "Authorization: Bearer sk-or-v1-xxxxx" \
https://openrouter.ai/api/v1/models
```
Some models require credits or have access restrictions. Check model availability on the OpenRouter dashboard.
OpenRouter has per-model rate limits. Switch models or upgrade your plan if hitting limits.
Get your API key at [openrouter.ai/keys](https://openrouter.ai/keys). New accounts receive free credits to get started.
# Remote Proxy
Source: https://docs.ccs.kaitran.ca/features/proxy/remote-proxy
Connect to a remote CLIProxyAPI server instead of localhost
## Overview
By default, CCS runs CLIProxyAPI as a local binary on your machine. With Remote Proxy, you can connect to a CLIProxyAPI server running on a different machine—Docker container, Kubernetes pod, or dedicated server.
**Use cases:**
* Run CLIProxyAPI on a powerful server while working from a laptop
* Share a single CLIProxyAPI instance across multiple machines
* Deploy CLIProxyAPI in Docker/Kubernetes for team use
* Reduce local resource usage
## Configuration Methods
CCS supports three ways to configure remote proxy, with the following priority:
| Priority | Method | Use Case |
| ----------- | --------------------- | ------------------- |
| 1 (Highest) | CLI Flags | One-time overrides |
| 2 | Environment Variables | CI/CD automation |
| 3 (Lowest) | config.yaml | Persistent settings |
***
## Skip Local OAuth
When connecting to a remote proxy with authentication, you can skip local OAuth entirely. This is useful when the remote server already has authenticated tokens.
**How it works:**
* If `--proxy-auth-token` is provided, CCS skips local OAuth flow
* The remote server handles all authentication
* No local token storage needed
**Use cases:**
* Shared team proxy with centralized auth
* CI/CD pipelines using pre-authenticated remote proxy
* Docker/Kubernetes deployments with service tokens
**Example:**
```bash theme={null}
# Skip local OAuth - remote server authenticates
ccs codex --proxy-host team-proxy.internal --proxy-auth-token
# Remote server handles OAuth, local client just proxies requests
```
**Configuration:**
```yaml theme={null}
cliproxy_server:
remote:
enabled: true
host: "team-proxy.internal"
auth_token: "service-token" # Enables skip-local-auth
```
***
## Dashboard Configuration
The easiest way to configure remote proxy is via the web dashboard:
1. Run `ccs config` to open the dashboard
2. Navigate to **Settings → Proxy** tab
3. Select **Remote** mode
4. Enter your remote server details:
* **Host**: Server hostname or IP address
* **Port**: CLIProxyAPI port (default: 8317)
* **Protocol**: HTTP or HTTPS
* **Auth Token**: Optional authentication token
* **Backend**: Select CLIProxy backend (original/plus)
5. Click **Test Connection** to verify connectivity
6. Configure fallback options as needed
Available since v7.37.0 - Backend switching allows choosing between original CLIProxyAPI and CLIProxyAPIPlus backends.
### Backend Selection
**Available Backends:**
* `original` - Standard CLIProxyAPI (default)
* `plus` - CCS-maintained CLIProxyAPIPlus community fork for plus-only providers
**Configuration:**
```yaml theme={null}
cliproxy:
backend: 'original' # or 'plus'
```
Dashboard dropdown provides visual selection with auto-detection of available backends.
***
## HTTPS Tunnel
When using `--proxy-protocol https`, CCS automatically starts a local HTTP→HTTPS tunnel that forwards requests to the remote HTTPS server. This is required because Claude Code's HTTP client (undici) doesn't support HTTPS in `ANTHROPIC_BASE_URL`.
**Architecture Flow:**
```
Claude Code → HTTP (localhost:random) → HttpsTunnelProxy → HTTPS (remote:443)
```
**Key Features:**
* **Automatic activation** - No manual flag needed, activates when `protocol=https`
* **Self-signed certificate support** - Use `--allow-self-signed` for dev/test environments
* **Transparent streaming** - No buffering, preserves real-time streaming
* **Authorization injection** - Auth token automatically added to outbound HTTPS requests
* **No SSL configuration** - Tunnel handles all HTTPS complexity internally
**Example:**
```bash theme={null}
# HTTPS with self-signed cert (tunnel activates automatically)
ccs codex --proxy-host secure.example.com --proxy-protocol https --allow-self-signed
# HTTPS with auth token
ccs codex --proxy-host proxy.internal --proxy-protocol https --proxy-auth-token
```
**Technical Details:**
* Tunnel binds to random available port on localhost
* Only Claude Code can access the tunnel (127.0.0.1)
* Tunnel terminates when CCS session ends
* No manual SSL certificate installation required
***
## Config File
Add the `cliproxy_server` section to `~/.ccs/config.yaml`:
```yaml theme={null}
# CLIProxy Server Configuration
cliproxy_server:
remote:
enabled: true # Enable remote mode
host: "192.168.1.100" # Remote server hostname/IP
port: 8317 # CLIProxyAPI port
protocol: http # http or https
auth_token: "" # Optional auth token
fallback:
enabled: true # Fallback to local if remote unreachable
auto_start: true # Auto-start local proxy on fallback
local:
port: 8317 # Local proxy port
auto_start: true # Auto-start when needed
```
### Configuration Options
| Option | Type | Default | Description |
| ------------ | ------- | ------- | ------------------------------- |
| `enabled` | boolean | `false` | Enable remote proxy mode |
| `host` | string | `""` | Remote server hostname or IP |
| `port` | number | `8317` | CLIProxyAPI port |
| `protocol` | string | `http` | `http` or `https` |
| `auth_token` | string | `""` | Bearer token for authentication |
| Option | Type | Default | Description |
| ------------ | ------- | ------- | ---------------------------------------------- |
| `enabled` | boolean | `true` | Fall back to local proxy if remote unreachable |
| `auto_start` | boolean | `true` | Auto-start local proxy on fallback |
| Option | Type | Default | Description |
| ------------ | ------- | ------- | ---------------------------------- |
| `port` | number | `8317` | Local CLIProxyAPI port |
| `auto_start` | boolean | `true` | Auto-start local proxy when needed |
***
## CLI Flags
Override configuration for a single command:
```bash theme={null}
# Connect to remote proxy
ccs codex --proxy-host 192.168.1.100 --proxy-port 8317
# Force local mode (ignore remote config)
ccs codex --local-proxy
# Strict remote mode (fail if unreachable, no fallback)
ccs codex --proxy-host remote.example.com --remote-only
# Use HTTPS with auth token
ccs codex --proxy-host secure.example.com --proxy-protocol https --proxy-auth-token "secret"
```
### Available Flags
| Flag | Description |
| ---------------------------- | ---------------------------------------- |
| `--proxy-host ` | Remote proxy hostname/IP |
| `--proxy-port ` | Proxy port (default: 8317) |
| `--proxy-protocol ` | Protocol: `http` or `https` |
| `--proxy-auth-token ` | Auth token for remote proxy |
| `--local-proxy` | Force local mode, ignore remote config |
| `--remote-only` | Fail if remote unreachable (no fallback) |
***
## Environment Variables
For CI/CD pipelines and automation:
```bash theme={null}
# Set remote proxy via environment
export CCS_PROXY_HOST="cliproxy-server.internal"
export CCS_PROXY_PORT="8317"
export CCS_PROXY_PROTOCOL="http"
export CCS_PROXY_AUTH_TOKEN="your-secret-token"
export CCS_PROXY_FALLBACK_ENABLED="1"
# Run CCS normally - it will use the remote proxy
ccs codex "implement the feature"
```
### Available Variables
| Variable | Description |
| ---------------------------- | ------------------------------- |
| `CCS_PROXY_HOST` | Remote proxy hostname |
| `CCS_PROXY_PORT` | Proxy port |
| `CCS_PROXY_PROTOCOL` | Protocol (`http`/`https`) |
| `CCS_PROXY_AUTH_TOKEN` | Auth token |
| `CCS_PROXY_FALLBACK_ENABLED` | Enable local fallback (`1`/`0`) |
***
## Docker Deployment
Run CLIProxyAPI in a Docker container:
```dockerfile theme={null}
# Dockerfile for CLIProxyAPI
FROM debian:bookworm-slim
# Download and install CLIProxyAPI
RUN apt-get update && apt-get install -y curl unzip \
&& curl -L -o cliproxy.zip https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/linux-amd64.zip \
&& unzip cliproxy.zip -d /opt/cliproxy \
&& chmod +x /opt/cliproxy/cli-proxy-api
EXPOSE 8317
CMD ["/opt/cliproxy/cli-proxy-api", "--port", "8317"]
```
```bash theme={null}
# Build and run
docker build -t cliproxy .
docker run -d -p 8317:8317 --name cliproxy cliproxy
# Configure CCS to use it
export CCS_PROXY_HOST="localhost"
export CCS_PROXY_PORT="8317"
ccs codex "hello"
```
***
## Kubernetes Deployment
Deploy CLIProxyAPI as a Kubernetes service:
```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
name: cliproxy
spec:
replicas: 1
selector:
matchLabels:
app: cliproxy
template:
metadata:
labels:
app: cliproxy
spec:
containers:
- name: cliproxy
image: your-registry/cliproxy:latest
ports:
- containerPort: 8317
---
apiVersion: v1
kind: Service
metadata:
name: cliproxy
spec:
selector:
app: cliproxy
ports:
- port: 8317
targetPort: 8317
```
Access from your local machine:
```bash theme={null}
# Port forward for local access
kubectl port-forward svc/cliproxy 8317:8317
# Or use the cluster DNS
export CCS_PROXY_HOST="cliproxy.default.svc.cluster.local"
```
***
## Fallback Behavior
When remote proxy is enabled but unreachable:
1. **With fallback enabled (default):**
* CCS prompts: "Remote proxy unreachable. Start local proxy? \[Y/n]"
* If auto-start enabled, starts local proxy automatically
* Continues with local proxy
2. **With `--remote-only` flag:**
* CCS fails immediately with error message
* No fallback, no prompt
3. **In non-interactive mode (no TTY):**
* Falls back to local if `fallback.enabled: true`
* Fails if fallback disabled or auto-start disabled
***
## Troubleshooting
**Error:** `Remote proxy unreachable: Connection refused`
**Solutions:**
* Verify the remote server is running: `curl http://HOST:PORT/health`
* Check firewall rules allow port 8317
* Ensure correct host/port configuration
**Error:** `Remote proxy unreachable: Authentication failed`
**Solutions:**
* Verify auth token matches server configuration
* Check token is correctly set (no extra spaces/quotes)
* Ensure server requires authentication
**Error:** `Remote proxy unreachable: Timeout`
**Solutions:**
* Check network connectivity to remote host
* Verify no proxy/VPN blocking the connection
* Increase timeout in config if needed
**Warning:** When using HTTPS with self-signed certificates
CCS automatically allows self-signed certificates when protocol is `https`.
A warning is displayed in verbose mode.
***
## Security Considerations
When exposing CLIProxyAPI to the network:
* Always use authentication tokens in production
* Consider HTTPS for encrypted connections
* Restrict access via firewall rules
* Use private networks when possible
**Best practices:**
* Use `--proxy-auth-token` for authenticated access
* Deploy behind a reverse proxy (nginx, Caddy) for HTTPS
* Limit network access to trusted IPs
* Rotate auth tokens periodically
# Browser Automation
Source: https://docs.ccs.kaitran.ca/features/workflow/browser-automation
Claude Browser Attach and Codex Browser Tools setup, policy, and safe launch controls
# Browser Automation
CCS exposes browser automation through two separate lanes:
* **Claude Browser Attach** reuses a Chrome or Chromium session through the
CCS-managed local `ccs-browser` MCP runtime.
* **Codex Browser Tools** injects Playwright MCP tooling into Codex-target
launches through the managed `ccs_browser` runtime config entry.
These lanes share the Settings workspace, but they do not promise a shared
browser session.
## Safe Defaults
New installs, and upgrades without explicit saved browser settings, keep both
lanes disabled and manual:
```yaml theme={null}
browser:
claude:
enabled: false
policy: manual
user_data_dir: "~/.ccs/browser/chrome-user-data"
devtools_port: 9222
codex:
enabled: false
policy: manual
```
`policy: manual` means the lane stays hidden unless the current launch opts in
with `--browser`.
## Dashboard Setup
Open:
```bash theme={null}
ccs config
# Settings -> Browser
```
The Browser tab lets you enable or disable each lane, inspect readiness, choose
the Claude attach user-data directory and DevTools port, and copy the Chrome
launch command.
## CLI Setup
```bash theme={null}
ccs help browser
ccs browser setup
ccs browser status
ccs browser doctor
ccs browser policy
ccs browser policy --all manual
ccs browser enable claude
ccs browser disable codex
```
`ccs browser setup` is the primary remediation flow for Claude Browser Attach.
`ccs browser doctor` is read-only and explains what is missing.
## One-Run Overrides
```bash theme={null}
ccs browser policy --all manual
ccs glm --browser "inspect the page"
ccs glm --no-browser "summarize the docs"
ccs default --target codex --browser "use browser tools for this run"
```
* `--browser` forces browser tooling on for the current launch when the lane is
enabled.
* `--no-browser` suppresses browser tooling for the current launch even when
policy is `auto`.
## Claude Attach Requirements
Claude Browser Attach needs a browser launched with remote debugging:
```bash theme={null}
# macOS
open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir="$HOME/.ccs/browser/chrome-user-data"
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.ccs/browser/chrome-user-data"
# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\\.ccs\\browser\\chrome-user-data"
```
Use a dedicated CCS browser data directory instead of your everyday browser
profile.
## Managed Runtime Files
* `~/.claude.json` stores the managed `mcpServers.ccs-browser` entry for Claude
Browser Attach.
* `~/.ccs/mcp/ccs-browser-server.cjs` is the local MCP runtime.
* Codex launches receive managed `ccs_browser` overrides when the Codex lane is
enabled and exposed.
## Security Notes
Browser automation may operate inside authenticated browser sessions. Keep the
automation profile separate from your daily browser profile, and never commit
browser paths, secrets, or generated session state.
## Related
* [Settings Workspace](/features/dashboard/settings-workspace)
* [CLI Flags](/reference/cli-flags#browser-automation-flags)
* [Configuration Schema](/reference/config-schema#browser-automation-configuration)
# Claude IDE Extension
Source: https://docs.ccs.kaitran.ca/features/workflow/claude-extension
Set up the Anthropic Claude extension for VS Code, Cursor, and Windsurf with CCS profiles
# Claude IDE Extension
CCS includes a native setup flow for the Anthropic Claude extension in VS Code-compatible hosts. The same resolver powers the CLI and dashboard, so API profiles, CCS auth accounts, CLIProxy-backed profiles, Copilot, and the current `default` profile all map to the correct environment shape.
## Supported Hosts
| Host | Settings Key | Notes |
| -------- | ---------------------------------- | ------------------------------------------ |
| VS Code | `claudeCode.environmentVariables` | Also emits `claudeCode.disableLoginPrompt` |
| Cursor | `claudeCode.environmentVariables` | Same schema as the VS Code host |
| Windsurf | `claude-code.environmentVariables` | Uses the legacy kebab-case extension keys |
## Preferred Setup: Shared Settings
Use `ccs persist ` when you want the Claude CLI and the IDE extension to share the same CCS profile via `~/.claude/settings.json`.
```bash theme={null}
ccs persist glm
ccs persist work
ccs persist default
```
This is the recommended path for daily use because CCS manages backup/restore for `~/.claude/settings.json` and keeps one shared source of truth.
## IDE-Local Snippet Setup
Use `ccs env --format claude-extension` when you want to edit the IDE host's own `settings.json` instead of the shared Claude settings file.
```bash theme={null}
ccs env glm --format claude-extension --ide vscode
ccs env work --format claude-extension --ide cursor
ccs env default --format claude-extension --ide windsurf
```
The command prints a copy-ready JSON object for the target host. Merge the emitted keys into that host's `settings.json`.
* `vscode` / `cursor`: `claudeCode.environmentVariables` and, when needed, `claudeCode.disableLoginPrompt`
* `windsurf`: `claude-code.environmentVariables`
Example output for VS Code or Cursor:
```json theme={null}
{
"claudeCode.environmentVariables": [
{
"name": "ANTHROPIC_BASE_URL",
"value": "http://127.0.0.1:3456"
},
{
"name": "ANTHROPIC_AUTH_TOKEN",
"value": "..."
}
],
"claudeCode.disableLoginPrompt": true
}
```
## Profile Resolution Rules
* **Account profiles** use `CLAUDE_CONFIG_DIR` so the extension opens the isolated Claude instance directory directly.
* **Default profile** clears CCS-managed transport env vars unless continuity inheritance maps `default` back to an account.
* **CLIProxy-backed and Copilot profiles** emit `ANTHROPIC_*` transport variables and still depend on their local proxy/daemon being reachable.
* **Settings/API profiles** emit the exact Anthropic-compatible environment from the selected `.settings.json`.
## Dashboard Workflow
Open the dashboard:
```bash theme={null}
ccs config
```
Then go to **Claude Extension** in the sidebar.
The page lets you:
* Pick a CCS profile and host
* Copy the preferred shared-settings command (`ccs persist `)
* Copy an IDE-local JSON snippet for VS Code, Cursor, or Windsurf
* Save reusable bindings with custom IDE settings paths
* Verify whether the target files are `applied`, `drifted`, `missing`, or `unconfigured`
* Apply or reset shared settings, IDE settings, or both
## Troubleshooting
### Extension still shows the login prompt
* Re-copy the correct host-specific snippet
* For VS Code or Cursor, make sure `claudeCode.disableLoginPrompt` is present when CCS emits it
### Profile works in CLI but not in the IDE
* For CLIProxy/Copilot-backed profiles, ensure the local proxy or daemon is reachable
* For account/default profiles, confirm the resolved `CLAUDE_CONFIG_DIR` exists
* Re-run `ccs persist ` if you want the shared settings path refreshed
## Next Steps
See `ccs persist`, `ccs env`, and `ccs config` command reference
Route Cursor models through CCS and pair them with the Claude extension host
# Codex Adapter
Source: https://docs.ccs.kaitran.ca/features/workflow/codex-adapter
Route CCS profiles to OpenAI Codex CLI with managed credential delivery
# Codex Adapter
Available since v7.62.0
CCS can delegate execution to the OpenAI Codex CLI as a native runtime target. Most CCS-backed Codex profiles use transient `-c` overrides and environment variable injection. The `ccsxp` shortcut also self-heals the native Codex provider entry needed for the CLIProxy Codex pool.
## Quick Start
```bash theme={null}
# Run with explicit target flag
ccs codex --target codex
# Use built-in aliases
ccs-codex "your prompt"
ccsx "your prompt"
# Launch a named native Codex auth profile
ccsx auth create work
ccsx work "your prompt"
# Codex-on-Codex shortcut (native Codex + CLIProxy Codex pool)
ccsxp "your prompt"
# Native Codex session (default profile, no CCS routing)
ccsx codex "your prompt"
```
## How It Works
For ordinary `ccsx` / `ccs-codex` launches, the Codex adapter uses transient runtime credential injection:
1. **Default profiles** pass through unchanged -- uses native Codex auth/config
2. **CCS-backed profiles** inject credentials via temporary `-c` overrides
3. API keys are delivered through `CCS_CODEX_API_KEY` env var, not written to disk
4. Profile and variant configs may persist `target: codex` for default routing
5. The Codex binary is probed for `--config` support before attempting overrides
For `ccsxp`, CCS intentionally uses the native Codex `model_provider="cliproxy"` path. Before launching, CCS repairs the active Codex `config.toml` only as far as needed to ensure `[model_providers.cliproxy]` points at the local CLIProxy Codex bridge:
```toml theme={null}
[model_providers.cliproxy]
name = "CLIProxy Codex"
base_url = "http://127.0.0.1:8317/api/provider/codex"
env_key = "CLIPROXY_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
```
If a `cliproxy` provider already exists with a custom `env_key`, CCS preserves that key and injects the managed token under the same environment variable for the spawned Codex process. Users should not need to add `CLIPROXY_API_KEY` to their shell profile after updating CCS.
```
CCS profile resolution
|
v
Credential build (provider, API key, base URL)
|
v
Codex binary detection + capability probe
|
v
Transient -c overrides injected:
-c model_provider="ccs_runtime"
-c model_providers.ccs_runtime.base_url="..."
-c model_providers.ccs_runtime.env_key="CCS_CODEX_API_KEY"
-c model_providers.ccs_runtime.wire_api="responses"
|
v
CCS_CODEX_API_KEY set in process env
|
v
Codex CLI spawned (replaces CCS process)
```
## Target Resolution Priority
CCS resolves the target CLI in this order:
| Priority | Source | Example |
| ----------- | ----------------------- | --------------------------------- |
| 1 (highest) | `--target` flag | `--target codex` |
| 2 | `argv[0]` binary name | calling via `ccsx` or `ccs-codex` |
| 3 | Profile `target` config | `target: codex` |
| 4 (default) | Fallback | `claude` |
API profiles and CLIProxy variants can persist `target: codex` in config. Use `--target codex` for one-off launches and persisted targets for profiles that should default to Codex.
## Built-in Aliases
| Binary Name | Target | Notes |
| --------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `ccs-codex` | `codex` (built-in) | Any profile on Codex CLI |
| `ccsx` | `codex` (short alias) | Any profile on Codex CLI |
| `ccsxp` | `codex` (power shortcut) | Forces `ccs codex --target codex`, ignores user `--target` overrides, and uses native `~/.codex` history by default |
| Custom via `CCS_TARGET_ALIASES` | `codex` | |
| Custom via `CCS_CODEX_ALIASES` (legacy) | `codex` | |
### Custom Aliases
```bash theme={null}
# Modern approach (unified env var)
export CCS_TARGET_ALIASES='codex=mycodex'
# Legacy approach (still supported)
export CCS_CODEX_ALIASES='mycodex'
# Create matching launcher
ln -s $(which ccs) /usr/local/bin/mycodex
mycodex "your prompt"
```
## Supported Profile Types
Codex is intentionally narrower than Claude or Droid in which profile types it accepts:
| Profile Type | Supported | Notes |
| ---------------------------- | --------- | --------------------------------------------------------- |
| `default` | Yes | Native Codex auth/config, no CCS routing |
| `cliproxy` provider=`codex` | Yes | Routed through CLIProxy Codex Responses bridge |
| `settings` with Codex bridge | Yes | Only when API profile resolves to a Codex CLIProxy bridge |
| `cliproxy` composite | No | Not proven native-Codex-safe |
| `settings` generic API | No | Claude/Droid only |
| `account` | No | Claude-only account isolation |
| `copilot` | No | Not a native Codex provider path |
If your Codex binary does not support `--config` overrides, CCS will throw an error for non-default profiles. Upgrade Codex before using CCS-backed Codex profiles.
## Model Aliases (Reasoning + Service Tier)
Codex models accept trailing tuning suffixes that CCS translates into the
underlying `reasoning_effort` and `service_tier` fields:
| Suffix | Effect |
| ------------------------------------------------ | ------------------------------------------------- |
| `-minimal`, `-low`, `-medium`, `-high`, `-xhigh` | Sets `reasoning_effort` |
| `-fast` | Sets `service_tier: priority` (Codex "fast" mode) |
Combine in either order:
```bash theme={null}
ccs codex --model gpt-5.4-minimal # minimal reasoning, default tier
ccs codex --model gpt-5.4-high # high reasoning, default tier
ccs codex --model gpt-5.4-fast # default reasoning, priority tier
ccs codex --model gpt-5.4-high-fast # high reasoning + priority tier
ccs codex --model gpt-5.4-fast-high # equivalent
```
Use `--thinking` for cross-provider control; use suffix aliases when you need
to pin a model identity (e.g., in saved profiles or API payloads).
## Environment Variables
| Variable | Description |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `CCS_TARGET_ALIASES` | Unified alias map (e.g., `codex=mycodex`) |
| `CCS_CODEX_ALIASES` | Legacy comma-separated argv0 names for codex target |
| `CCS_CODEX_API_KEY` | Injected at runtime for CCS-backed profiles (do not set manually) |
| `CLIPROXY_API_KEY` | Injected at runtime for `ccsxp` when the Codex `cliproxy` provider uses the default `env_key` |
| `CCSXP_CODEX_HOME` | Optional history/config root override for `ccsxp`; otherwise native `~/.codex` is used |
## Native Codex Auth Profiles
`ccsx auth` manages native Codex account profiles under `~/.ccs/codex-instances/`.
After creating a profile, launch it directly by name:
```bash theme={null}
ccsx auth create work
ccsx work "your prompt"
```
`ccsx ` resolves `` from the Codex profile registry before normal
CCS profile resolution, so Codex profiles stay separate from Claude account
profiles. `ccsxp` is intentionally separate from `ccsx auth`; it ignores
`CCS_CODEX_PROFILE` and keeps using its CLIProxy Codex pool behavior.
Each `ccsx auth` profile keeps its own `auth.json`, history, and sessions. Native
Codex resources stay shared from `~/.codex`: `config.toml`, `agents/`, `skills/`,
and `plugins/cache/`.
```text theme={null}
~/.ccs/codex-instances//
├── auth.json, history.jsonl, sessions/ # Profile-local state
├── config.toml -> ~/.codex/config.toml
├── agents/ -> ~/.codex/agents/
├── skills/ -> ~/.codex/skills/
└── plugins/ # Local parent for profile metadata
└── cache/ -> ~/.codex/plugins/cache/ # Shared plugin payloads
```
Only the cache subtree is linked; the profile's parent `plugins/` directory remains
local and may hold profile-specific plugin metadata. `ccsx auth create ` and
direct `ccsx ` launches repair the shared links idempotently before Codex starts.
This keeps relative entries such as `agents/reviewer.toml` valid and prevents stale
first-launch skill warnings after plugin installs or updates.
On Windows, symlinks may require Developer Mode or elevated privileges. When a cache
symlink is unavailable, CCS copies the current `~/.codex/plugins/cache/` snapshot into
the profile. Later plugin updates may require another profile launch or
`ccsx auth create --force` repair to copy newly missing entries; existing
profile-local cache files are preserved.
If you launch `ccsx` from your home directory, native Codex may also report that
`~/.codex/config.toml` contains user-level-only keys such as `model_providers` or
`notify` in a project-local config. That warning comes from Codex's current
working directory config discovery, not from `ccsx auth` profile selection.
## Dashboard: Codex Page
The dashboard includes a dedicated Codex page at `ccs config` -> Sidebar -> Compatible -> Codex CLI, with three tabs:
### Overview Tab
* **Binary detection** -- shows whether Codex CLI is installed and its path
* **Config file status** -- checks `~/.codex/config.toml` existence and validity
* **Supported flows table** -- which profile types work with Codex target
* **Quick command snippets** -- copy-paste starters for common Codex commands
### Control Center Tab
Guided editor for the user-layer Codex config (`~/.codex/config.toml`):
* **Top-level settings** -- model defaults, history, instructions
* **Project trust** -- trusted directory paths (validated as absolute or `~/...`)
* **Profiles** -- named configuration profiles
* **Model providers** -- custom provider endpoints
* **MCP servers** -- Model Context Protocol server configuration
* **Feature flags** -- toggle experimental features (reset to Codex defaults available)
The Control Center edits only the user config layer. The effective runtime config may differ due to trusted repo layers, CCS transient overrides (`-c` flags, `CCS_CODEX_API_KEY`), and the `ccsxp` managed `model_providers.cliproxy` repair.
**Raw TOML editor** is available as an escape hatch for unsupported or fidelity-sensitive edits. Structured controls are disabled while raw TOML is dirty or invalid.
### Docs Tab
* Upstream Codex documentation links
* CLIProxy provider setup guidance
* CCS Codex adapter reference
## Security
* **No persisted credentials** -- API keys are injected into the spawned Codex process, not written to `~/.codex/config.toml`
* **Scoped provider repair** -- `ccsxp` may create or repair `[model_providers.cliproxy]`, but does not store the API key there
* **Process-scoped keys** -- `CCS_CODEX_API_KEY` exists only in the spawned process environment
* **Anthropic env stripping** -- CCS removes stale `ANTHROPIC_*` env vars before spawning Codex
* **Binary validation** -- Codex binary is probed for capability before credential injection
## Usage Examples
```bash theme={null}
# Default Codex session (native auth)
ccsx "explain this code"
# Named native Codex auth profile
ccsx work "summarize this repo"
# CCS-backed Codex via CLIProxy bridge
ccsx codex "implement auth flow"
# Codex-on-Codex power shortcut (strips any --target override)
ccsxp "your prompt"
# Explicit target flag
ccs codex --target codex "your prompt"
# With reasoning effort
ccsx codex --effort xhigh "deep analysis"
```
`ccsxp` is an opinionated shortcut equivalent to native Codex using CCS's CLIProxy Codex pool. It strips any user-supplied `--target` flags, repairs the native `cliproxy` provider entry when needed, and injects the managed token into the provider's configured `env_key`. By default, `ccsxp` pins `CODEX_HOME` to native `~/.codex` so history and resume state stay with regular Codex sessions. Set `CCSXP_CODEX_HOME` only when you intentionally want a separate ccsxp history root.
## Related
* [Codex Provider](/providers/oauth/codex) -- OAuth authentication and model configuration
* [Droid Adapter](/features/workflow/droid-adapter) -- Alternative CLI target (Factory Droid)
* [Dashboard](/features/dashboard/overview) -- Visual configuration interface
* [Target Architecture](/reference/architecture) -- Technical details of the adapter system
# Concurrent Sessions
Source: https://docs.ccs.kaitran.ca/features/workflow/concurrent-sessions
Run multiple Claude instances simultaneously
# Concurrent Sessions
Run multiple Claude CLI instances simultaneously. Different account profiles normally use different Claude config directories, while launching the same profile twice reuses the same directory and shared state.
## Overview
```bash theme={null}
# Terminal 1
ccs work "implement feature X"
# Terminal 2 (simultaneously)
ccs personal "research topic Y"
# Different profiles = separate default state
```
## Architecture
CCS uses `CLAUDE_CONFIG_DIR` to select the Claude config directory for each account profile:
```
~/.ccs/instances/work/ # Work account
~/.ccs/instances/personal/ # Personal account
```
When you run `ccs work "task"`:
1. Sets `CLAUDE_CONFIG_DIR=~/.ccs/instances/work/`
2. Claude loads credentials from that directory
3. That session reuses the `work` profile's state directory
That gives you a simple rule of thumb:
* Different profiles such as `work` and `personal` normally use different directories
* The same profile such as `work` + `work` reuses one directory
* If you configure continuity inheritance, different profile names can intentionally reuse the same directory too
## Instance Structure
Each account profile gets its own default directory:
```
~/.ccs/instances/work/
├── .anthropic/ # Claude-managed metadata
├── session-env/ # Chat history
├── todos/ # Task lists
├── logs/ # Execution logs
├── file-history/ # Recent file context
├── shell-snapshots/ # Shell continuity artifacts
├── debug/ # Debug artifacts
├── commands/ # Shared link/copy in non-bare profiles
└── skills/ # Shared link/copy in non-bare profiles
```
## Performance
| Metric | First Use | Subsequent |
| ---------- | ------------------------ | ---------- |
| Activation | \~20-35ms | \~5-10ms |
| Memory | \~3-5 KB per activation | - |
| Disk | \~200-700 KB per profile | - |
## Limitations
Running the **same profile** in multiple terminals is allowed, but both terminals reuse the same `CLAUDE_CONFIG_DIR` and shared state. Use different profiles when you want stronger separation.
```bash theme={null}
# Shared state on purpose:
ccs work "task1" # Terminal 1
ccs work "task2" # Terminal 2 - same profile, same state directory
# Separate state:
ccs work "task1" # Terminal 1
ccs personal "task2" # Terminal 2
```
This is not a special CCS-only restriction. Any two launches that point at the same Claude config directory share mutable state.
### Other Limitations
* `CLAUDE_CONFIG_DIR` is undocumented (keep Claude CLI updated)
* Same-profile launches share history, todos, logs, and other mutable artifacts
* Non-bare profiles share commands, skills, agents, plugins, `settings.json`, and `CLAUDE.md` via `~/.ccs/shared/`
* Sessions/logs accumulate (manual cleanup if needed)
For account and native session recovery, see [Resume the Correct Session Lane](/providers/concepts/claude-accounts#resume-the-correct-session-lane).
## Shared Resources
By default, non-bare account profiles reuse the shared CCS layout for commands, skills, agents, plugins, `settings.json`, and user `CLAUDE.md`.
```bash theme={null}
# Recreate shared symlinks after changing shared resources
ccs sync
```
If you created a profile with `--bare`, it opts out of that shared layout on purpose.
## Cleanup
```bash theme={null}
# Check sizes
du -sh ~/.ccs/instances/*
# Clear sessions
rm -rf ~/.ccs/instances/work/session-env/*
# Clear logs
rm -rf ~/.ccs/instances/work/logs/*
```
# Cursor IDE Bridge (Legacy)
Source: https://docs.ccs.kaitran.ca/features/workflow/cursor
Deprecated compatibility bridge for the older local Cursor daemon workflow
# Cursor IDE Bridge (Legacy)
Beta
This page documents the **deprecated local Cursor IDE bridge**. It is still
available for migration and backward compatibility, but it is no longer the
current `ccs cursor` product surface.
Use [`ccs cursor --auth`](/providers/oauth/cursor) for the **current Cursor
provider path**. The commands on this page now live under
`ccs legacy cursor ...`.
**Beta Feature — Use at Your Own Risk**
* Uses Cursor's internal ConnectRPC API (reverse-engineered, may break on IDE updates)
* Tokens expire every 24h and must be re-imported
* Windows users must use manual auth (`--manual` flag)
## Quick Start
```bash theme={null}
ccs legacy cursor enable # Enable the legacy bridge in config
ccs legacy cursor auth # Auto-detect credentials from Cursor SQLite
ccs legacy cursor start # Start local daemon
ccs legacy cursor probe # Verify runtime health
ccs legacy cursor status # Inspect auth + daemon state
```
Older `ccs cursor ` invocations are still shimmed for a migration
window, but they print a deprecation warning and forward to the legacy bridge.
On macOS and Linux, auto-detect requires `sqlite3` in your `PATH`. Windows does
not support auto-detect.
## Authentication
CCS auto-detects credentials from Cursor's local SQLite database.
| Platform | SQLite Path |
| -------- | --------------------------------------------------------------------- |
| macOS | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` |
| Linux | `~/.config/Cursor/User/globalStorage/state.vscdb` |
| Windows | Manual only — see below |
```bash theme={null}
# Auto-detect (macOS/Linux)
ccs legacy cursor auth
# Manual import
ccs legacy cursor auth --manual --token --machine-id <32-hex-id>
```
Credentials are stored at `~/.ccs/cursor/credentials.json` (mode `0o600`).
Auto-detect uses the `sqlite3` CLI on macOS and Linux. If `sqlite3` is
missing, use manual import.
Token validation: access token must be >50 chars, machine ID must be exactly 32 hex characters. Tokens expire after 24h (or per JWT `exp` claim).
## CLI Subcommands
| Subcommand | Description |
| ---------- | ----------------------------------------- |
| `auth` | Import token (auto-detect or `--manual`) |
| `status` | Show integration, auth, and daemon status |
| `models` | List available models with 5-min cache |
| `start` | Start local daemon |
| `stop` | Stop daemon gracefully |
| `enable` | Enable integration in `config.yaml` |
| `disable` | Disable integration in `config.yaml` |
| `help` | Show help |
## Configuration
```yaml theme={null}
# ~/.ccs/config.yaml
cursor:
enabled: false # Must be true to use
port: 20129 # Daemon port (default: 20129)
auto_start: false # Auto-start daemon with CCS
ghost_mode: true # Disable Cursor telemetry (recommended)
model: gpt-5.3-codex # Default model
opus_model: "" # Optional: override opus tier
sonnet_model: "" # Optional: override sonnet tier
haiku_model: "" # Optional: override haiku tier
```
## Available Models
Model list is discovered dynamically from `api2.cursor.sh/v1/models` with a 5-minute TTL cache. The list below reflects typical available models, but may change as Cursor updates their offering.
GPT-5.3 Codex (default), GPT-5.2, GPT-5.1, GPT-5, GPT-5 Fast, GPT-5 Mini
Claude 4.6 Opus, Claude 4.5 Sonnet, Claude 4.5 Haiku
Gemini 3 Pro, Gemini 3 Flash, Gemini 2.5 Flash, Grok Code
**Model fallback:** If the requested model is unavailable in Cursor's catalog, CCS falls back to the catalog-resolved default model for the current available model list and logs a debug message.
## Dashboard Controls
Open `ccs config`, then navigate to the **Deprecated** Cursor IDE bridge page if
you still rely on the local daemon workflow.
* Import auth automatically or manually
* Start/stop the daemon
* Save runtime config (port, auto-start, ghost mode)
* Use searchable model pickers for large live catalogs
* Edit raw `~/.ccs/cursor.settings.json` when needed
## Daemon Management
The daemon spawns as a detached process and uses a settled-once pattern for startup — health is polled until the daemon signals ready or the timeout is reached (30s). Proper 413 (payload too large) responses are returned for oversized requests, and the daemon aborts cleanly on client disconnect.
**Daemon API surface:**
* `POST /v1/chat/completions` for OpenAI-compatible clients
* `POST /v1/messages` for Anthropic-compatible clients
* `GET /v1/models` for dynamic model discovery
| Path | Purpose |
| -------------------------------- | --------------------------- |
| `~/.ccs/cursor/credentials.json` | Auth credentials |
| `~/.ccs/cursor/daemon.pid` | Daemon PID file |
| `~/.ccs/cursor.settings.json` | Settings override |
| `~/.ccs/config.yaml` | Main config (`cursor:` key) |
Stop behavior: sends `SIGTERM`, waits 5s, escalates to `SIGKILL` if still running.
Health check: `GET /health` — expects `{ "service": "cursor-daemon" }` in response.
## Dashboard API
The CCS dashboard exposes REST endpoints for managing the integration:
| Endpoint | Method | Purpose |
| ------------------------------ | --------- | --------------------- |
| `/api/cursor/status` | GET | Daemon + auth status |
| `/api/cursor/auth/auto-detect` | POST | Import from SQLite |
| `/api/cursor/auth/import` | POST | Manual token import |
| `/api/cursor/models` | GET | List available models |
| `/api/cursor/daemon/start` | POST | Start daemon |
| `/api/cursor/daemon/stop` | POST | Stop daemon |
| `/api/cursor/settings` | GET / PUT | Read/write config |
## Troubleshooting
Ensure Cursor IDE has been launched and logged in at least once. The SQLite
DB is only created after first login. On macOS/Linux, confirm `sqlite3` is
installed and in `PATH`. Try `ccs legacy cursor auth --manual` if
auto-detect continues to fail.
Check if port 20129 is in use: `lsof -i :20129`. Change `cursor.port` in
`config.yaml` if needed, then restart with `ccs legacy cursor start`.
Tokens expire every 24h. Re-run `ccs legacy cursor auth` to refresh
credentials from your local Cursor installation.
Auto-detect is not available on Windows. Use manual import:
```bash theme={null}
ccs legacy cursor auth --manual --token --machine-id
```
Find your token in Cursor's developer tools or Keychain equivalent.
## Current Recommendation
Use the legacy bridge only when you specifically need the reverse-engineered
local Cursor daemon path. For new setups:
* use [Cursor Provider](/providers/oauth/cursor) for `ccs cursor --auth`
* keep this page only for `ccs legacy cursor ...`
# Task Delegation
Source: https://docs.ccs.kaitran.ca/features/workflow/delegation
Delegate tasks to appropriate models
# Task Delegation
CCS includes intelligent task delegation via the `/ccs` meta-command, allowing you to route tasks to the most appropriate model.
## Basic Delegation
```bash theme={null}
# Delegate planning to GLM (saves Sonnet tokens)
/ccs glm /plan "add user authentication"
# Delegate coding to GLM
/ccs glm /code "implement auth endpoints"
# Quick questions with Haiku
/ccs haiku /ask "explain this error"
```
## Continue Previous Session
Resume the last delegation session to continue a task:
```bash theme={null}
# Continue last delegation with follow-up
/ccs:continue "add error handling to that feature"
# Works with any previous delegation context
/ccs:continue "also add unit tests"
```
This preserves the context from your previous delegation, enabling multi-step workflows without repeating information.
## Benefits
* Save tokens by delegating simple tasks to cheaper models
* Use right model for each task automatically
* Reusable commands across all projects (user-scope)
* Seamless integration with existing workflows
* Session continuity with `/ccs:continue`
## Headless Delegation
Execute prompts without interactive session using `-p` or `--prompt`:
```bash theme={null}
# Direct prompt execution
ccs -p "your prompt"
ccs --prompt "your prompt"
# With specific profile
ccs glm -p "implement feature"
ccs codex --prompt "analyze this code"
```
Use cases:
* CI/CD pipelines
* Automated scripts
* Batch processing
* Remote/headless servers
## Workflow Example
**Scenario**: Building a new payment integration feature
```bash theme={null}
# Step 1: Architecture & Planning (needs Claude's intelligence)
ccs
/plan "Design payment integration with Stripe"
# → Claude Sonnet 4.5 thinks deeply about edge cases
# Step 2: Implementation (straightforward, use GLM)
ccs glm
/code "implement the payment webhook handler"
# → GLM 4.6 writes code efficiently, saves usage
# Step 3: Code Review (needs deep analysis)
ccs
/review "check payment handler for security"
# → Claude Sonnet catches subtle vulnerabilities
# Step 4: Bug Fixes (simple)
ccs glm
/fix "update error message formatting"
# → GLM handles routine fixes
# Step 5: Continue with follow-up
/ccs:continue "also add logging to the webhook"
# → Continues from previous context
```
**Result**: Best model for each task, lower costs, better quality.
## Task-Model Mapping
| Task Type | Recommended Model | Why |
| ------------------------- | --------------------- | --------------------------------- |
| Architecture | Claude Sonnet | Deep reasoning, edge cases |
| Planning | Claude Sonnet | System design |
| Code Review | Claude Sonnet | Security, subtle bugs |
| Implementation | GLM 5 | Efficient, cost-effective |
| Simple Fixes | GLM 5 | Routine changes |
| Long Docs | Kimi | 1M context window |
| Quick Iterations | GPT-5 Codex Mini | Fast responses, low overhead |
| Reasoning-First API Tasks | `/ccs --km` | Kimi API reasoning |
| Thinking Tasks | Claude Sonnet / Codex | Strong reasoning and review depth |
## Rate Limit Management
```bash theme={null}
# Working on complex refactoring with Claude
ccs
/plan "refactor authentication system"
# Claude hits rate limit mid-task
# → Error: Rate limit exceeded
# Switch to GLM instantly
ccs glm
# Continue working without interruption
# Rate limit resets? Switch back
ccs
```
## Profile Selection
Force specific profiles for delegation:
```bash theme={null}
# Force GLM for simple tasks
/ccs --glm "task description"
# Force Kimi for long context
/ccs --kimi "analyze this large codebase"
# Force Codex for quick iterations
/ccs --codex "quick prototype"
# Force Kimi for Coding API reasoning
/ccs --km "reason through this failing test"
```
# Droid Adapter
Source: https://docs.ccs.kaitran.ca/features/workflow/droid-adapter
Route CCS profiles to alternative CLI targets with multi-target adapter system
# Droid Adapter
CCS can delegate execution to alternative CLI targets beyond Claude Code. The Droid adapter routes profiles to the Droid CLI using the same CCS configuration system.
## Quick Start
```bash theme={null}
# Run with explicit target flag
ccs glm --target droid
# Use built-in alias (ccsd = droid target)
ccsd glm "your prompt"
# Custom aliases via env var
export CCS_DROID_ALIASES=mydroid,alt-droid
mydroid glm "your prompt"
```
## Target Resolution Priority
CCS resolves the target CLI in this order:
| Priority | Source | Example |
| ----------- | -------------------------- | ------------------------------ |
| 1 (highest) | `--target` flag | `--target droid` |
| 2 | Per-profile `target` field | `target: droid` in config.yaml |
| 3 | `argv[0]` binary name | calling via `ccsd` |
| 4 (default) | Fallback | `claude` |
## Built-in Aliases
`ccsd` is the busybox-style argv0 shorthand — symlink or copy the `ccs` binary as `ccsd` and it auto-routes to the droid target:
```bash theme={null}
# Create ccsd symlink
ln -s $(which ccs) /usr/local/bin/ccsd
# Then use directly
ccsd glm "your prompt" # Equivalent to: ccs glm --target droid
```
| Binary Name | Target |
| ------------------------------ | ------------------ |
| `ccsd` | `droid` (built-in) |
| Custom via `CCS_DROID_ALIASES` | `droid` |
### Custom Aliases via `CCS_DROID_ALIASES`
Set comma-separated argv0 aliases that all map to the droid target:
```bash theme={null}
export CCS_DROID_ALIASES=mydroid,alt-droid,factory-ccs
mydroid glm "prompt" # Routes to droid
alt-droid codex "prompt" # Also routes to droid
```
## Droid Detection
CCS locates the Droid binary in order:
1. `CCS_DROID_PATH` env var — explicit path override
2. PATH lookup via `which droid` (Unix) or `where.exe droid` (Windows)
**Install Droid CLI:**
```bash theme={null}
npm i -g @factory/cli
```
## Environment Variables
| Variable | Description |
| ------------------- | ----------------------------------------------------------- |
| `CCS_DROID_ALIASES` | Comma-separated argv0 binary names that map to droid target |
| `CCS_DROID_PATH` | Explicit absolute path to the droid binary |
## Config Integration
Droid adapter writes credentials to `~/.factory/settings.json` using Droid's config format:
* Profiles stored as `customModels[]` entries with `CCS `-prefixed display names
* Atomic file writes via temp file + rename
* File locking prevents concurrent write races
* Profile names validated: alphanumeric, underscore, and hyphen only
### Per-Profile Target Config
Set `target: droid` on any API, variant, or composite profile to always route that profile to Droid without needing the `--target` flag:
```yaml theme={null}
# API profile
profiles:
my-api:
provider: openai
target: droid # Always use Droid for this profile
# CLIProxy variant
cliproxy:
variants:
my-variant:
provider: gemini
target: droid # Routes this variant to Droid CLI
# Composite variant
cliproxy:
variants:
my-composite:
composite: true
opus: gemini
sonnet: agy
target: droid # Routes composite to Droid CLI
```
Per-profile `target` is NOT supported for profile types: `cliproxy`, `copilot`,
and `account`. Legacy `glmt` compatibility profiles now follow the normal
settings-profile flow after runtime normalization, but new setups should still
migrate to `glm` or `km`.
## Unsupported Profile Types
The following profile types do not support droid routing:
| Profile Type | Workaround |
| ---------------- | ---------------------------- |
| `cliproxy` (raw) | Use variant profiles instead |
| `copilot` | Not supported |
| `account` | Not supported |
## Dashboard: Droid Page
The dashboard includes a dedicated Droid page at `http://localhost:3000/droid` with three tabs:
### Overview Tab
* **Binary detection** — shows whether Droid CLI is installed and its path
* **File status** — checks `~/.factory/settings.json` existence and validity
* **Warnings** — alerts for missing binary, corrupt config, or stale locks
* Auto-refreshes diagnostics every 10 seconds
### BYOK Tab (Bring Your Own Key)
Register custom LLM endpoints for use with Droid:
**Quick Settings Card:**
* Toggle settings like `enableThinking`, `enableArtifacts`
* Configure default model selection
**Reasoning Controls Card:**
* Per-model reasoning effort settings
* Provider-specific configuration:
* **Anthropic:** `thinking.budget_tokens` (4K-64K tokens)
* **OpenAI:** `reasoning.effort` (low/medium/high/max/xhigh)
* **Generic:** `reasoning_effort` (string value)
**Custom Models:**
* CCS-managed models (prefixed "CCS ") registered in `~/.factory/settings.json`
* Three provider types supported:
* `anthropic` — Anthropic Messages API
* `openai` — OpenAI Responses API
* `generic-chat-completion-api` — OpenAI-compatible (Groq, DeepInfra, Ollama, local)
* Smart provider detection: explicit hint → URL inference → model name inference
**Raw JSON Editor:**
* Direct editing of `~/.factory/settings.json`
* Conflict detection via mtime comparison (prevents overwriting external changes)
### Docs Tab
* Links to Factory Droid documentation
* Provider API references
* Quick access to relevant CCS docs
## Reasoning Effort Sync
CCS syncs reasoning effort settings between CLI and dashboard:
```bash theme={null}
# CLI override flags
ccs glm --target droid --thinking high
ccs km --target droid --effort medium
```
Dashboard reasoning controls write provider-specific config to `~/.factory/settings.json`. The Droid CLI reads these at startup.
## Security
* **No symlink traversal** — refuses read/write if target is symlink
* **Atomic writes** — temp file + rename prevents corruption
* **File locking** — 10s stale timeout, exponential backoff
* **Corruption backup** — `.bak` file created before writes
* **File permissions** — 0o600 (user-only read/write)
## Usage Examples
```bash theme={null}
ccs glm --target droid # Run GLM on Droid (explicit flag)
ccs km --target droid # Run Kimi for Coding on Droid
ccsd glm # Same via ccsd alias
ccs glm # Run GLM on Claude (default)
ccsd codex "prompt" # Run Codex on Droid
ccsd km "prompt" # Run Kimi API profile on Droid
```
## Related
* [Dashboard](/features/dashboard/overview) — Visual configuration interface
* [Updates Center](/features/config/updates-center) — Rollout tasks for Droid setup
* [Extended Thinking](/features/ai/extended-thinking) — Thinking/reasoning budget configuration
# Headless Workflow
Source: https://docs.ccs.kaitran.ca/features/workflow/headless-workflow
Use CCS on servers without a browser
# Headless Workflow
Use OAuth providers on servers or remote machines without browser access.
Available since v7.37.0 - Enhanced interactive OAuth mode with auto-detection for SSH sessions and paste-callback flow.
## Interactive OAuth Modes
Auto-detected on SSH sessions - no manual configuration needed.
CCS supports two interactive OAuth modes for headless environments:
### Paste-Callback Mode (Recommended)
Recommended for most headless scenarios.
```bash theme={null}
ccs codex --headless
# Or force paste-callback mode
ccs codex --paste-callback
# Output:
# Open this URL on any device to authenticate:
# https://auth.openai.com/authorize?...
#
# After authorizing, paste the callback URL here:
# Waiting for callback URL...
```
**How it works:**
1. CCS generates authentication URL
2. You open URL on any device with a browser
3. Complete OAuth login
4. GitHub/Provider redirects to callback URL
5. Copy callback URL from browser address bar
6. Paste URL back into CCS terminal
7. CCS extracts token and continues
**Benefits:**
* Works over any SSH connection
* No port forwarding required
* No localhost access needed
* Faster than traditional headless mode
### Port Forwarding Mode
```bash theme={null}
ccs codex --headless
# Output:
# OAuth callback server listening on port 8080
# Forward this port to your local machine:
# ssh -L 8080:localhost:8080 user@remote
#
# Then open: http://localhost:8080/auth
```
**How it works:**
1. CCS starts local callback server
2. You forward port via SSH tunnel
3. Complete OAuth in browser on local machine
4. Callback reaches remote CCS via tunnel
**Use when:**
* SSH port forwarding is available
* Multiple users sharing the same server
* Network policies allow port forwarding
## Auto-Detection
SSH session detection is automatic - CCS chooses the best mode for you.
CCS automatically detects SSH sessions via:
* `SSH_CONNECTION` environment variable
* `SSH_CLIENT` environment variable
* TTY detection
When SSH is detected, CCS defaults to **paste-callback mode** unless `--headless` explicitly requests traditional flow.
## Usage
```bash theme={null}
ccs codex --headless
# Output:
# Open this URL on any device to authenticate:
# https://auth.openai.com/authorize?...
#
# Waiting for authentication...
```
## How It Works
1. CCS generates an authentication URL
2. You open the URL on any device with a browser
3. Complete OAuth login
4. CCS detects when tokens are cached
5. Session continues
## Use Cases
* SSH sessions on remote servers
* Docker containers
* CI/CD pipelines (with pre-cached tokens)
* Headless Linux environments
## Commands
```bash theme={null}
# Codex headless
ccs codex --headless "prompt"
# Claude headless
ccs claude --headless "prompt"
# Kimi headless
ccs kimi --headless "prompt"
```
## Pre-Caching Tokens
For automated environments, authenticate locally first:
1. Run `ccs codex --auth` on local machine
2. Copy `~/.ccs/cliproxy/auth/*.json` to remote server
3. Use without `--headless` flag
# OpenCode Sync Plugin
Source: https://docs.ccs.kaitran.ca/features/workflow/opencode-sync
Use the community opencode-ccs-sync plugin to keep OpenCode aligned with your active CCS providers
# OpenCode Sync Plugin
Use the community
[`opencode-ccs-sync`](https://github.com/JasonLandbridge/opencode-ccs-sync)
plugin to keep OpenCode aligned with your live CCS setup automatically.
Community integration by
[Jason Landbridge](https://github.com/JasonLandbridge).
This page is the public home for the setup guidance that was preserved from the
community contribution around OpenCode sync. The README keeps the attribution
visible, while the actual setup steps live here so they stay public and easy to
maintain.
## What It Does
After you add the plugin and restart OpenCode, it:
* performs an initial sync on startup
* automatically re-syncs when `~/.ccs/config.yaml` changes
* watches live `~/.ccs/*.settings.json` provider files
* exposes only the providers and models currently selected in CCS
* writes managed `ccs-*` entries into your OpenCode config
## OpenCode Config Example
```jsonc theme={null}
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-ccs-sync"]
}
```
## Suggested Flow
1. Configure the providers or API profiles you actually use in CCS.
2. Install the `opencode-ccs-sync` plugin in OpenCode.
3. Restart OpenCode once so the initial sync runs.
4. Update CCS normally after that. The plugin handles re-sync from your live
CCS configuration files.
## Where This Fits
This is a community integration, not a core CCS runtime. Use it when you want
OpenCode to reflect your current CCS provider selection without manually
rewriting OpenCode config every time CCS changes.
## Related Docs
Understand `config.yaml` and provider settings before syncing them outward
Review `ccs env` and other third-party integration surfaces
See where CCS configuration and provider management live in the dashboard
See broader CLI ecosystem integration in the containerized setup
# Configuration
Source: https://docs.ccs.kaitran.ca/getting-started/configuration
CCS configuration file format, paths, and management
# Configuration
CCS uses a unified YAML configuration file. Current schema version: **13**.
## Config File Location
```bash theme={null}
~/.ccs/config.yaml
```
```powershell theme={null}
%USERPROFILE%\.ccs\config.yaml
```
## Config Structure
```yaml theme={null}
version: 13
default: default
accounts:
work:
config_dir: ~/.ccs/instances/work
context_mode: isolated
profiles:
glm:
settings_file: ~/.ccs/glm.settings.json
km:
settings_file: ~/.ccs/km.settings.json
cliproxy:
providers: {}
proxy:
profile_ports: {}
thinking:
mode: auto
budget: 8192
browser:
claude:
enabled: false
policy: manual
codex:
enabled: false
policy: manual
channels:
enabled: [telegram, discord]
image_analysis:
enabled: true
```
### Key Sections
| Section | Purpose |
| ---------------- | ----------------------------------------------------------- |
| `version` | Config schema version (current: 13) |
| `default` | Default profile used when running `ccs` with no arguments |
| `accounts` | Named Claude account instances with isolated directories |
| `profiles` | API key profile references (settings JSON files) |
| `cliproxy` | CLIProxy OAuth provider settings |
| `proxy` | OpenAI-compatible local proxy ports and routing |
| `thinking` | Extended thinking defaults for supported providers |
| `browser` | Claude Browser Attach and Codex Browser Tools policy |
| `channels` | Official channel integrations (Telegram, Discord, iMessage) |
| `image_analysis` | Vision/image analysis feature toggle |
## Config Precedence
Settings are resolved in this order (highest to lowest priority):
```
CLI Flags > Environment Variables > config.yaml > Built-in Defaults
```
For example, `--proxy-host` overrides `CCS_PROXY_HOST`, which overrides
`config.yaml`.
## Dashboard Management
The easiest way to manage config is through the dashboard:
```bash theme={null}
ccs config
```
The dashboard opens in your browser on the current session URL. It provides a
GUI for:
* managing OAuth provider accounts and tokens
* creating and editing API profiles
* viewing real-time quota status
* configuring proxy and advanced settings
All `env` values must be strings. Booleans or objects will cause crashes on
Windows PowerShell.
## Environment Variables
### Core
| Variable | Description | Default |
| ----------------- | ------------------------------- | -------------------- |
| `CCS_CONFIG` | Override config file location | `~/.ccs/config.yaml` |
| `NO_COLOR` | Disable colored terminal output | `false` |
| `CCS_CLAUDE_PATH` | Override Claude CLI binary path | Auto-detected |
| `CCS_DEBUG` | Enable verbose debug logging | `false` |
### Remote Proxy
| Variable | Description | Example |
| ---------------------------- | ---------------------------------------- | ------------------- |
| `CCS_PROXY_HOST` | Remote proxy hostname | `proxy.example.com` |
| `CCS_PROXY_PORT` | Remote proxy port | `8317` |
| `CCS_PROXY_AUTH_TOKEN` | Proxy authentication token | `your-token` |
| `CCS_PROXY_PROTOCOL` | Protocol (`http`/`https`) | `https` |
| `CCS_PROXY_FALLBACK_ENABLED` | Fall back to local proxy if remote fails | `true` |
| `CCS_ALLOW_SELF_SIGNED` | Accept self-signed SSL certificates | `false` |
### Integration and Migration
| Variable | Description |
| -------------------- | ------------------------------------------ |
| `CCS_SKIP_MIGRATION` | Skip automatic config migration on startup |
| `CCS_UNIFIED_CONFIG` | Enable unified config mode (`config.yaml`) |
| `CCS_WEBSEARCH_SKIP` | Disable WebSearch hook integration |
| `CCS_SKIP_PREFLIGHT` | Skip API key validation on startup |
## Migration from v1 JSON
If you have a legacy `~/.ccs/config.json`, CCS migrates it to `config.yaml`
automatically on first run after upgrade. No manual action needed.
To trigger migration manually:
```bash theme={null}
CCS_MIGRATE=true ccs
```
## Next Steps
Run a complete first provider flow after configuration
Create profiles for Anthropic, GLM, Kimi, and more
Configure multiple Claude account instances
Compare all supported providers
# First Session
Source: https://docs.ccs.kaitran.ca/getting-started/first-session
Run your first CCS session with Claude or another supported provider
# First Session
After installing CCS, run your first session in under 2 minutes.
## Step 1: Choose a Provider
```bash theme={null}
# Browser opens for Claude OAuth
ccs
```
Requires a Claude Pro or Max subscription.
```bash theme={null}
# Browser opens for OpenAI OAuth
ccs codex "review this code"
```
Works well as a first browser-OAuth route.
```bash theme={null}
# Device code flow (no browser required)
ccs kiro "help me debug this"
```
Free tier via AWS Builder ID.
```bash theme={null}
# Z.AI GLM — requires API key setup first
ccs glm "quick code fix"
```
See [API Profiles](/providers/concepts/api-profiles) for setup.
Other supported routes such as GHCP, Gemini, iFlow, and Antigravity are
documented in [Provider Overview](/providers/concepts/overview). This page
keeps the first-run path focused on the safest baseline examples.
## Step 2: Authenticate
On first run, CCS triggers OAuth automatically.
CCS spawns a local OAuth callback server and opens the provider login page.
For Device Code providers (Kiro, Kimi), a code and URL are shown in
the terminal instead.
Complete login with the account for your chosen provider.
OAuth credentials are cached at `~/.ccs/cliproxy/auth/`. Future runs skip
this step.
CCS launches the selected target runtime with the chosen provider injected
as the API backend. By default, that target runtime is Claude Code.
## Step 3: Start Coding
```bash theme={null}
# Interactive session (default)
ccs codex
# One-shot with prompt
ccs kiro "what does this regex do: ^[a-z]+$"
# Pass a prompt directly
ccs glm "refactor this function to use async/await"
```
### How Profile Switching Works
Each `ccs ` command injects different environment variables into the
active target runtime:
```
ccs codex → ANTHROPIC_BASE_URL=http://127.0.0.1:8317/api/provider/codex
ccs kiro → ANTHROPIC_BASE_URL=http://127.0.0.1:8317/api/provider/kiro
ccs glm → ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
ccs → Default Claude account (no proxy)
```
Switching takes under 1 second. Running `ccs codex` in one terminal and `ccs glm`
in another keeps those sessions separate and avoids conflicts.
## Dashboard
Open the visual configuration dashboard at any time:
```bash theme={null}
ccs config
```
The dashboard shows all profiles, OAuth provider status, quota usage, and lets
you manage API keys without editing files.
## Quick Examples
```bash theme={null}
# Switch between providers instantly
ccs "design the auth layer" # Default Claude
ccs glm "implement user service" # Z.AI GLM (cost-optimized)
ccs codex "security review" # OpenAI Codex
# Extended thinking / reasoning
ccs --effort high "debug this regression"
ccs codex --effort xhigh "complex refactor"
ccs km "reason through this architecture change"
# Multi-account: work vs personal
ccs work "review PR #123"
ccs personal "help with side project"
```
## Next Steps
Compare OAuth providers, Claude accounts, and API profiles
Config file format, precedence rules, and env vars
Run multiple Claude subscriptions simultaneously
Bring your own API keys
# Installation
Source: https://docs.ccs.kaitran.ca/getting-started/installation
Install CCS via npm, verify setup, and configure your first profile
# Installation
## Prerequisites
* Node.js 18+
* npm
* [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation)
* PowerShell 5.1+ (pre-installed on Windows 10+)
* Node.js 18+
* [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation)
## Install CCS
```bash theme={null}
npm install -g @kaitranntt/ccs
```
```bash theme={null}
yarn global add @kaitranntt/ccs
```
```bash theme={null}
pnpm add -g @kaitranntt/ccs
```
```bash theme={null}
bun add -g @kaitranntt/ccs
```
## Verify Installation
```bash theme={null}
ccs --version
# ccs/7.x.x darwin-arm64 node-v22.x.x
```
## First Run
```bash theme={null}
# Opens OAuth for default Claude account
ccs
# Or open the dashboard to configure providers and profiles
ccs config
# Run setup wizard
ccs setup
```
## What Gets Installed
The postinstall script creates `~/.ccs/` with default templates:
```
~/.ccs/
├── config.yaml # Unified config (schema v12)
├── glm.settings.json # Z.AI GLM profile template
├── instances/ # Claude account instances
├── cliproxy/ # OAuth provider auth tokens
└── shared/ # Shared commands/skills/agents
```
If you run `npm install --ignore-scripts`, config files won't be created
automatically. Re-run without that flag or run `ccs setup` manually.
## Upgrade
```bash theme={null}
npm update -g @kaitranntt/ccs
# Or force reinstall
ccs update --force
```
## Uninstall
```bash theme={null}
npm uninstall -g @kaitranntt/ccs
```
This removes the CCS command but preserves your `~/.ccs/` configuration
directory.
## Platform Notes
### macOS / Linux
No special configuration needed. CCS detects Claude CLI from PATH.
```bash theme={null}
# Override Claude CLI location if detection fails
export CCS_CLAUDE_PATH="/custom/path/to/claude"
```
### Windows (PowerShell 5.1+)
CCS auto-detects Claude CLI via these paths in order:
```
%USERPROFILE%\.local\bin\claude.exe
%APPDATA%\npm\claude.cmd
```
If detection fails, override with:
```powershell theme={null}
$env:CCS_CLAUDE_PATH = "C:\custom\path\to\Claude.exe"
```
### Docker
CCS can run in Docker containers. Mount your `~/.ccs` and `~/.claude`
directories:
```bash theme={null}
docker run -v ~/.ccs:/root/.ccs -v ~/.claude:/root/.claude \
node:22 npx @kaitranntt/ccs codex "your task"
```
## Troubleshooting
### `ccs: command not found`
npm global bin directory is not in PATH. Add it:
```bash theme={null}
# Find npm global bin
npm config get prefix
# e.g. /usr/local
# Add to PATH in ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"
```
### Permission Denied (Linux/macOS)
```bash theme={null}
# Fix npm global permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Then reinstall
npm install -g @kaitranntt/ccs
```
## Next Steps
Authenticate and run your first query
Understand config format and options
Choose your first provider
See the dashboard and workflow surfaces before deeper setup
# Product Tour
Source: https://docs.ccs.kaitran.ca/getting-started/product-tour
See the current CCS dashboard shape before you install
# Product Tour
This page mirrors the current routed CCS dashboard in `ccs/cli` `dev`. The
route names below match the live UI; the screenshots are representative
workspace surfaces from the same dashboard family.
## Current Dashboard Shape
| Sidebar group | Current pages |
| ----------------- | --------------------------------------------- |
| General | Home, Analytics |
| Identity & Access | API Profiles, CLIProxy, Accounts, Shared Data |
| Compatible CLIs | Claude Extension, Codex CLI, Factory Droid |
| Deprecated | GitHub Copilot, Cursor IDE (Legacy) |
| System | Health, Logs, Settings |
There is also an on-demand **Updates Center** at `/updates`, but it stays out of
the main sidebar on purpose.
## Representative Workspaces
### Usage Analytics
CCS binds the dashboard to `localhost` by default. Use `ccs config --host
0.0.0.0` when you want to open the dashboard from another device, and protect
it first with `ccs config auth setup`.
`ccs glmt` remains compatibility-only for legacy scripts and configs. New API
setups should use `ccs glm` or `ccs km`.
## 4. Create Accounts (Optional)
For concurrent Claude sessions with different accounts:
```bash theme={null}
# Create work profile
ccs auth create work
# Complete OAuth login with work account
# Create personal profile
ccs auth create personal
# Complete OAuth login with personal account
# Use them
ccs work "review code" # Terminal 1
ccs personal "side project" # Terminal 2 (concurrent)
```
## Next Steps
See the dashboard and workflow before going deeper
Follow the full first-run flow after installation
Set up work, personal, and team accounts
Configure Codex, Kiro, Claude, Kimi, and more
Set up GLM, Kimi, OpenRouter, Novita, and custom endpoints
Explore the configuration dashboard
Connect CCS profiles to VS Code, Cursor, and Windsurf
# Introduction
Source: https://docs.ccs.kaitran.ca/introduction
CCS (Claude Codex Switch) - Multi-provider profile and runtime orchestration across Claude Code and compatible CLIs
Run work, personal, and team Claude accounts simultaneously with separate
account directories by default. Optional shared context groups.
Access Codex, Kiro, Claude, Kimi, and more via OAuth with no API keys.
Copilot remains a deprecated compatibility path for existing setups.
Bring your own keys for Claude, Z.AI GLM, Kimi for Coding, Novita,
Alibaba, or run local models via llama.cpp
## Why CCS?
**Built for developers with both Claude subscription and alternative model access.**
### Task-Appropriate Model Selection
| Model | Best For | Setup |
| -------------------------- | ----------------------------------------------- | ---------------------------- |
| Claude Sonnet 4.6 | Complex architecture, system design, debugging | Claude Pro/Max or Direct API |
| GPT-5 Codex | High-signal implementation and review work | Codex OAuth or Codex CLI |
| GPT-5 Codex Mini | Quick iterations and prototypes | Codex OAuth or Codex CLI |
| OpenRouter (300+ models) | Unified access, model variety, cost flexibility | API key |
| Z.AI GLM 5 (`ccs glm`) | Simple fixes, routine implementations, docs | API key |
| Kimi OAuth (`ccs kimi`) | Long-context analysis (1M tokens) | OAuth |
| Kimi for Coding (`ccs km`) | Reasoning-first API workflows | API key |
| Alibaba Coding Plan | Cost-effective code generation, 1M context | API key |
| Local llama.cpp | Offline, private, zero-cost inference | Self-hosted |
| Qwen3 Coder | Code-focused tasks | API key |
### Rate Limit Management
No more manual config editing when Claude hits rate limits:
```bash theme={null}
ccs # Using Claude, hit rate limit
ccs glm # Switch to GLM instantly
ccs codex # Or use Codex via OAuth
ccs # Switch back when limit resets
```
`ccs glmt` is deprecated and no longer marketed as a supported surface. Use
`ccs glm` for Z.AI API profiles and `ccs km` for reasoning-first Kimi API
profiles.
## Quick Start
```bash theme={null}
npm install -g @kaitranntt/ccs
```
```bash theme={null}
ccs config
```
Opens the dashboard on the current session URL so you
can configure accounts, providers, and profiles visually.
```bash theme={null}
ccs # Default Claude
ccs work # Work account
ccs codex # Codex via OAuth
ccs glm # GLM via API
ccs km # Kimi for Coding via API
```
## Features
* **Instant profile switching** - One command, under 1 second switch
* **Concurrent sessions** - Run multiple accounts in different terminals
* **Cross-platform** - macOS, Linux, Windows (PowerShell, CMD, Git Bash)
* **Flexible setup** - Use IDE-local snippets or shared `~/.claude/settings.json` setup
* **Visual dashboard** - Configure everything via `ccs config`
* **Claude IDE extension setup** - Generate shared or IDE-local settings for VS Code, Cursor, and Windsurf
* **Localized dashboard** - English, Simplified Chinese, Vietnamese, Japanese, Korean, and Brazilian Portuguese
* **Extended Thinking** - Cross-provider `--thinking` controls plus native Claude `--effort` session overrides
* **Docker deployment** - Run CCS in containerized environments via Docker or Docker Compose
* **Official channels** - Community support on Telegram, Discord, and iMessage
## Get Started
See the dashboard, provider controls, and workflow surfaces first
Install CCS via npm or package manager
Get up and running in 2 minutes
Run an end-to-end first provider flow with a concrete example
# Alibaba Coding Plan Provider
Source: https://docs.ccs.kaitran.ca/providers/api/alibaba
Access Qwen3 Coder models via Alibaba Cloud Coding Plan API key
# Alibaba Coding Plan Provider
Access Alibaba Cloud's Qwen3 Coder models through the Coding Plan API — a cost-effective option for high-volume coding tasks with strong context windows.
## Overview
| Field | Details |
| ------------------------ | ----------------------------------------------------------- |
| **Preset ID** | `alibaba-coding-plan` |
| **Aliases** | `alibaba`, `acp` |
| **Default Profile Name** | `albb` |
| **Default Model** | `qwen3-coder-plus` |
| **Base URL** | `https://coding-intl.dashscope.aliyuncs.com/apps/anthropic` |
| **Auth Method** | API Key (`sk-sp-...`) |
| **Category** | Recommended |
## Quick Start
```bash theme={null}
# Create profile with preset (prompts for API key)
ccs api create --preset alibaba-coding-plan
# Or use alias
ccs api create --preset alibaba
# Run with default profile name
ccs albb "review this pull request"
```
## Authentication
Alibaba Coding Plan uses API key authentication — no OAuth required.
Sign in to [Alibaba Cloud Model Studio](https://bailian.console.aliyun.com/) and obtain a Coding Plan key.
Key format: `sk-sp-...`
Coding Plan keys are distinct from standard Alibaba Cloud API keys. Obtain them from the Coding Plan section of Model Studio.
```bash theme={null}
ccs api create --preset alibaba-coding-plan
# Enter profile name (default: albb)
# Enter API key: sk-sp-...
```
```bash theme={null}
ccs albb "implement binary search"
```
## Available Models
| Model | Input/M | Output/M | Context | Best For |
| ------------------- | ------- | -------- | ------- | ------------------------------- |
| `qwen3-coder-plus` | \$1.00 | \$5.00 | 1M | Balanced coding tasks (default) |
| `qwen3-coder-flash` | \$0.30 | \$1.50 | 1M | Fast, high-volume tasks |
Both models support 1M token context windows. Cache rates: creation = input price × 1.0, read = input price × 0.2.
## Configuration
### Via Dashboard
```bash theme={null}
ccs config
# Navigate to API Profiles → Create → Alibaba Coding Plan
```
The Alibaba Coding Plan card appears in the recommended presets sidebar.
### Manual Configuration
Create `~/.ccs/albb.settings.json`:
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic",
"ANTHROPIC_AUTH_TOKEN": "sk-sp-your-key-here",
"ANTHROPIC_MODEL": "qwen3-coder-plus"
}
}
```
Register in `~/.ccs/config.yaml`:
```yaml theme={null}
profiles:
albb: ~/.ccs/albb.settings.json
```
### Model Switching
```bash theme={null}
# Use flash model for speed
ANTHROPIC_MODEL=qwen3-coder-flash ccs albb "quick code review"
# Or edit settings file
# "ANTHROPIC_MODEL": "qwen3-coder-flash"
```
## Commands Reference
```bash theme={null}
# Create profile
ccs api create --preset alibaba-coding-plan
ccs api create --preset alibaba # alias
ccs api create --preset acp # alias
# Use profile (default name: albb)
ccs albb "your prompt"
# List configured API profiles
ccs api list
# Delete profile
ccs api delete albb
```
## Troubleshooting
### 401 Unauthorized
**Symptom:** Authentication error on first request
**Cause:** Invalid or incorrectly formatted API key
**Solution:**
* Verify key starts with `sk-sp-`
* Re-create profile: `ccs api delete albb && ccs api create --preset alibaba-coding-plan`
* Confirm key is a Coding Plan key (not a standard Alibaba Cloud key)
### 404 Not Found
**Symptom:** Model not found error
**Cause:** Model name mismatch
**Solution:** Use exact model IDs: `qwen3-coder-plus` or `qwen3-coder-flash`
### High Latency
The Coding Plan endpoint routes through Alibaba Cloud's international network. For users in China, consider the domestic endpoint instead.
## Storage Locations
| Path | Description |
| --------------------------- | ------------------------------------------- |
| `~/.ccs/albb.settings.json` | Profile settings (base URL, API key, model) |
| `~/.ccs/config.yaml` | Profile registration |
## Cost Information
| Model | Input/M | Output/M | Cache Create/M | Cache Read/M |
| ------------------- | ------- | -------- | -------------- | ------------ |
| `qwen3-coder-plus` | \$1.00 | \$5.00 | \$1.00 | \$0.20 |
| `qwen3-coder-flash` | \$0.30 | \$1.50 | \$0.30 | \$0.06 |
Pricing sourced from Alibaba Cloud Model Studio. Verify current rates at [alibabacloud.com](https://www.alibabacloud.com/help/en/model-studio/model-pricing).
## Next Steps
Configure other API-based providers
Qwen account linking is unavailable; use this API-key route
Access 300+ models via single API key
Compare all supported providers
# Anthropic Direct API
Source: https://docs.ccs.kaitran.ca/providers/api/anthropic-direct
Use your own Anthropic API key to access Claude models directly
# Anthropic Direct API
Use your Anthropic API key directly to access Claude models without going through CLIProxy. Perfect for users who already have Anthropic subscriptions and want direct API control.
## Overview
| Field | Details |
| ------------------------ | ------------------------------------- |
| **Preset ID** | `anthropic` |
| **Aliases** | None |
| **Default Profile Name** | `anthropic` |
| **Default Model** | `claude-sonnet-4-5-20250929` |
| **Base URL** | `api.anthropic.com` (auto-configured) |
| **Auth Method** | API Key (`sk-ant-...`) |
| **Category** | Recommended |
## Quick Start
```bash theme={null}
# Create profile with your Anthropic API key
ccs api create --preset anthropic
# When prompted, enter your API key (sk-ant-...)
# Use the profile
ccs anthropic "explain this code"
```
## Authentication
### Getting Your API Key
Go to [console.anthropic.com](https://console.anthropic.com)
Click on your profile → **Settings** → **API Keys**
Click **Create Key** and copy the generated key
Format: `sk-ant-...`
Keep this key secure. Treat it like a password. Do not commit to git or share publicly.
```bash theme={null}
ccs api create --preset anthropic
# Paste your API key when prompted
```
### Rotating Keys
When you need to change your API key:
```bash theme={null}
# Re-create or update the profile
ccs api create --preset anthropic
# Or edit the profile manually
ccs config
# Navigate to anthropic profile and update ANTHROPIC_AUTH_TOKEN
```
## Configuration
### Default Setup
```bash theme={null}
# Interactive setup
ccs api create --preset anthropic
# You'll be prompted for:
# - API Key: sk-ant-...
# - Profile name (default: anthropic)
```
### Manual Configuration
Edit `~/.ccs/config.yaml`:
```yaml theme={null}
profiles:
anthropic:
env:
ANTHROPIC_BASE_URL: "" # Leave empty - uses official Anthropic API
ANTHROPIC_AUTH_TOKEN: "sk-ant-your-key-here"
ANTHROPIC_MODEL: "claude-sonnet-4-5-20250929"
ANTHROPIC_DEFAULT_OPUS_MODEL: "claude-opus-4-1-20250805"
ANTHROPIC_DEFAULT_SONNET_MODEL: "claude-sonnet-4-5-20250929"
ANTHROPIC_DEFAULT_HAIKU_MODEL: "claude-3-5-haiku-20241022"
```
### Custom Base URL (Advanced)
For organizations using Anthropic Workbench or custom deployments:
```bash theme={null}
# Via CLI
ccs api create --preset anthropic --base-url https://your-custom-api.anthropic.com
# Or manual config
profiles:
anthropic-custom:
env:
ANTHROPIC_BASE_URL: "https://your-custom-api.example.com"
ANTHROPIC_AUTH_TOKEN: "sk-ant-your-key"
ANTHROPIC_MODEL: "claude-sonnet-4-5-20250929"
```
## Available Models
### Claude 5 Series (Latest)
| Model | Context | Use Case |
| ---------------- | ------- | ----------------------------------------------------------------- |
| `claude-fable-5` | 1M | Adaptive thinking, most demanding reasoning and long-horizon work |
| `claude-opus-5` | 1M | Adaptive thinking, premium reasoning and complex work |
### Claude 4.8 Series
| Model | Context | Use Case |
| ----------------- | ------------------ | -------------------------------------------- |
| `claude-opus-4-8` | 200K (1M extended) | Adaptive extended thinking, hardest problems |
Opt in explicitly via `ANTHROPIC_MODEL` or the dashboard; the default profile model is unchanged.
### Claude 4.6 Series
| Model | Context | Use Case |
| ------------------- | ------- | ----------------------------------- |
| `claude-opus-4-6` | 200K | Extended thinking, hardest problems |
| `claude-sonnet-4-6` | 200K | Balanced (latest generation) |
### Claude 4.5 Series
| Model | Context | Use Case |
| ---------------------------- | ------- | -------------------------------- |
| `claude-opus-4-1-20250805` | 200K | Complex reasoning, system design |
| `claude-sonnet-4-5-20250929` | 200K | Balanced (default profile model) |
| `claude-3-5-haiku-20241022` | 100K | Fast responses, high volume |
### Claude 3 Series (Previous)
| Model | Context | Use Case |
| -------------------------- | ------- | ---------------- |
| `claude-3-opus-20240229` | 200K | Complex analysis |
| `claude-3-sonnet-20240229` | 200K | General purpose |
| `claude-3-haiku-20240307` | 100K | Fast tasks |
## Usage Examples
### Basic Chat
```bash theme={null}
# Use default model
ccs anthropic "explain quantum computing"
# Check current model
ccs anthropic "what model are you?"
```
### Model Selection
```bash theme={null}
# Use Opus for complex tasks
ANTHROPIC_MODEL=claude-opus-4-1-20250805 ccs anthropic "design a microservices architecture"
# Use Haiku for quick tasks
ANTHROPIC_MODEL=claude-3-5-haiku-20241022 ccs anthropic "what's 2+2?"
```
### Temperature and Creativity
```bash theme={null}
# Higher temperature = more creative
ANTHROPIC_TEMPERATURE=0.9 ccs anthropic "brainstorm creative names"
# Lower temperature = more deterministic
ANTHROPIC_TEMPERATURE=0.2 ccs anthropic "calculate the answer"
# Default = 1.0
ccs anthropic "analyze this code"
```
### Response Length Control
```bash theme={null}
# Longer responses
ANTHROPIC_MAX_TOKENS=2000 ccs anthropic "write a detailed guide"
# Shorter responses
ANTHROPIC_MAX_TOKENS=300 ccs anthropic "summarize briefly"
```
## API Features Supported
### Full Feature Support
Direct Anthropic API access supports all Claude features:
* ✅ Vision (image analysis)
* ✅ Extended thinking
* ✅ Tool use (function calling)
* ✅ Batch processing
* ✅ Long context (200K tokens)
* ✅ Token counting
* ✅ Streaming
### How to Enable
```bash theme={null}
# Vision is handled automatically - just describe or share images
ccs anthropic "analyze this screenshot"
# Extended thinking (via ANTHROPIC_THINKING_BUDGET)
ANTHROPIC_THINKING_BUDGET=8000 ccs anthropic "solve this complex problem"
```
## Billing & Rate Limits
### Usage Tracking
Check your API usage:
```bash theme={null}
# View current usage in dashboard
ccs config # Navigate to anthropic profile section
# Check spending at console.anthropic.com/dashboard
```
### Rate Limits
Default limits (can be increased):
| Limit | Value | Applies To |
| ------------------- | ------ | ------------------------- |
| Requests/minute | 600 | All models |
| Tokens/minute | Varies | Per model subscription |
| Concurrent requests | 10 | Streaming + non-streaming |
Enterprise users can request higher limits at Anthropic console.
### Cost Estimation
Visit [console.anthropic.com/pricing](https://console.anthropic.com/pricing) for current rates.
| Model | Base Input | Base Output | Fast Input | Fast Output |
| --------------- | ---------: | ----------: | ---------: | ----------: |
| `claude-opus-5` | \$5 | \$25 | \$10 | \$50 |
Rates are per million tokens.
Typical usage:
* Claude 3.5 Sonnet: \~\$3-10/month for light use
* Extended thinking: Additional cost based on thinking tokens
## Comparison with CLIProxy Providers
| Feature | Direct API | CLIProxy Claude |
| --------------- | --------------------------- | ---------------------------- |
| **Cost** | Pay-per-use | Depends on CLIProxy setup |
| **Setup** | Single API key | OAuth browser login |
| **Privacy** | Your key, direct connection | Your key through CLIProxy |
| **Rate limits** | Anthropic's limits | CLIProxy's limits |
| **Best for** | Existing Anthropic users | Users with CLIProxy accounts |
## Troubleshooting
### Invalid API Key
**Symptom:** `Error: 401 Unauthorized` or `Invalid authentication credentials`
**Solutions:**
1. Verify key starts with `sk-ant-`
2. Check key hasn't expired or been revoked
3. Copy key again from console.anthropic.com/settings/keys
4. Update with: `ccs api create --preset anthropic`
```bash theme={null}
# Debug: check what key is being used
ccs config | grep ANTHROPIC_AUTH_TOKEN
```
### Rate Limited
**Symptom:** `Error: 429 Too Many Requests` or `Rate limit exceeded`
**Solutions:**
1. Wait a few minutes before retrying
2. Reduce concurrent requests
3. Use Haiku for high-volume tasks (cheaper, faster)
4. Request higher limits at Anthropic console
```bash theme={null}
# Switch to faster model
ANTHROPIC_MODEL=claude-3-5-haiku-20241022 ccs anthropic "quick task"
# Or reduce token limit
ANTHROPIC_MAX_TOKENS=500 ccs anthropic "brief response"
```
### Connection Timeout
**Symptom:** `Error: Request timeout` or `ECONNREFUSED`
**Causes & Solutions:**
* Network issue — Check internet connection
* API down — Check [Anthropic status](https://status.anthropic.com)
* Firewall blocked — Check firewall/proxy settings
```bash theme={null}
# Test connection
curl -I https://api.anthropic.com
# Increase timeout if on slow network
ANTHROPIC_TIMEOUT=60000 ccs anthropic "test"
```
### Insufficient Balance
**Symptom:** `Error: Insufficient balance` or `Credit limit exceeded`
**Solutions:**
1. Check remaining balance at console.anthropic.com/dashboard
2. Add payment method or credits
3. Switch to lower-cost model (Haiku)
## Cost Optimization
### Use Right Model for Task
```bash theme={null}
# Complex tasks (use Opus)
ANTHROPIC_MODEL=claude-opus-4-1-20250805 ccs anthropic "design system architecture"
# Routine tasks (use Sonnet - default)
ccs anthropic "fix this function"
# Quick tasks (use Haiku)
ANTHROPIC_MODEL=claude-3-5-haiku-20241022 ccs anthropic "translate to Spanish"
```
### Limit Response Length
```bash theme={null}
# Reduce tokens to lower cost
ANTHROPIC_MAX_TOKENS=500 ccs anthropic "summarize in 100 words"
```
### Batch Processing
For bulk operations, use Anthropic's Batch API (available through direct API):
```bash theme={null}
# Store multiple requests in a file
# Process them with batch API for 50% discount
# See Anthropic docs for batch API usage
```
## Storage Locations
| Path | Description |
| ----------------------- | ------------------------------------- |
| `~/.ccs/config.yaml` | Stores encrypted API key in profile |
| `~/.ccs/settings.json` | Dashboard settings and preferences |
| `console.anthropic.com` | API key management and usage tracking |
## Security Best Practices
1. **Never commit API keys** — Use `.gitignore` for config files
2. **Rotate keys regularly** — Generate new keys, revoke old ones
3. **Use environment variables** — For CI/CD pipelines instead of files
4. **Monitor usage** — Check console.anthropic.com regularly for suspicious activity
5. **Limit key scope** — Create separate keys for different applications if possible
## Next Steps
Learn more about creating and managing API profiles
Compare with OAuth-based Claude accounts
Explore other available providers
Manage profiles via web interface
# Llama.cpp Provider
Source: https://docs.ccs.kaitran.ca/providers/api/llamacpp
Local GGUF model inference via llama.cpp server for private, offline AI
# Llama.cpp Provider
Run GGUF-quantized LLaMA models locally via llama.cpp server with zero API costs, complete privacy, and offline capability.
## Overview
| Field | Details |
| ------------------------ | ------------------------- |
| **Preset ID** | `llamacpp` |
| **Aliases** | None |
| **Default Profile Name** | `llamacpp` |
| **Default Model** | `llama3-8b` |
| **Base URL** | `http://127.0.0.1:8080` |
| **Auth Method** | Local (no API key needed) |
| **Category** | Recommended |
## Quick Start
```bash theme={null}
# 1. Start llama.cpp server (in separate terminal)
./server --host 0.0.0.0 --port 8080 -m /path/to/model.gguf
# 2. Create CCS profile
ccs api create --preset llamacpp
# or use the direct shortcut (creates profile automatically if needed)
ccs llamacpp "explain quantum computing"
# 3. Use the profile
ccs llamacpp "explain quantum computing"
```
## Prerequisites
### Installing llama.cpp
```bash theme={null}
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
```
**On macOS (with Metal acceleration):**
```bash theme={null}
make clean
make -j LLAMA_METAL=1
```
**On Linux (with CUDA):**
```bash theme={null}
make clean
make -j LLAMA_CUDA=1
```
**On Windows (CPU only):**
```bash theme={null}
make clean
make -j
```
Download a GGUF-quantized model from [Hugging Face](https://huggingface.co/models?search=gguf):
```bash theme={null}
# Example: LLaMA 3 8B (Q4_0 quantization - 4-5GB)
wget https://huggingface.co/QuantFactory/Meta-Llama-3-8B-Instruct-GGUF/resolve/main/Meta-Llama-3-8B-Instruct.Q4_0.gguf
# Or: Phi-3 (smaller, faster)
wget https://huggingface.co/microsoft/Phi-3-mini-4k-instruct-gguf/resolve/main/Phi-3-mini-4k-instruct-Q4.gguf
```
Q4\_0 quantization (4-bit) offers best balance of speed and quality. Q5\_K\_M is higher quality but slower.
```bash theme={null}
./server --help | head -20
# Should show server options
```
### Model Selection
Popular GGUF models for coding and general tasks:
| Model | Size | Speed | Quality | RAM | Context |
| ---------------- | ----- | --------- | ------------------ | ----- | ------- |
| Phi-3 Mini (Q4) | 2.3GB | Very Fast | Good | 4GB | 4K |
| LLaMA 3 8B (Q4) | 4.7GB | Fast | Good | 8GB | 8K |
| LLaMA 3 70B (Q4) | 40GB | Slow | Excellent | 48GB+ | 8K |
| Mistral 7B (Q4) | 4.2GB | Very Fast | Good | 8GB | 8K |
| Qwen3 Coder (Q4) | 5.2GB | Fast | Excellent (coding) | 8GB | 128K |
**Recommended for coding:** Qwen3 Coder, LLaMA 3 8B, or Phi-3
## Configuration
### Default Setup
```bash theme={null}
# Create profile with defaults (localhost:8080)
ccs api create --preset llamacpp
# Profile is created with:
# Base URL: http://127.0.0.1:8080
# Model: llama3-8b
# No API key required
```
### Custom Configuration
If llama.cpp server runs on different host/port:
```bash theme={null}
# Via CLI
ccs api create --preset llamacpp --base-url http://192.168.1.100:8080
# Or manual config in ~/.ccs/config.yaml
profiles:
llamacpp-custom:
env:
ANTHROPIC_BASE_URL: "http://192.168.1.100:8080"
ANTHROPIC_AUTH_TOKEN: "llamacpp"
ANTHROPIC_MODEL: "llama3-8b"
ANTHROPIC_DEFAULT_OPUS_MODEL: "llama3-70b"
ANTHROPIC_DEFAULT_SONNET_MODEL: "llama3-8b"
ANTHROPIC_DEFAULT_HAIKU_MODEL: "phi3-mini"
```
## Starting llama.cpp Server
### Basic Usage
```bash theme={null}
# Start with a specific model
./server -m /path/to/model.gguf
# With default CCS settings (accessible on localhost:8080)
./server -m /path/to/model.gguf --host 0.0.0.0 --port 8080
```
### Performance Tuning
```bash theme={null}
# Use GPU acceleration (Metal on macOS, CUDA on Linux)
./server -m /path/to/model.gguf \
--host 0.0.0.0 --port 8080 \
-ngl 99 # Offload all layers to GPU
# Use specific number of threads
./server -m /path/to/model.gguf \
--host 0.0.0.0 --port 8080 \
-t 8 # Use 8 threads
# Limit context to reduce memory usage
./server -m /path/to/model.gguf \
--host 0.0.0.0 --port 8080 \
-c 2048 # Limit to 2K context (default 2048)
```
### Running Multiple Models
```bash theme={null}
# Terminal 1: Primary model on :8080
./server -m /path/to/qwen3-coder.gguf --host 0.0.0.0 --port 8080 -ngl 99
# Terminal 2: Alternative model on :8081
./server -m /path/to/llama3-8b.gguf --host 0.0.0.0 --port 8081 -ngl 99
# Terminal 3: Use CCS with either
ccs llamacpp "coding task" # Uses 8080
ANTHROPIC_BASE_URL=http://localhost:8081 ccs llamacpp "analysis task"
```
## Usage Examples
### Basic Chat
```bash theme={null}
# Use default model
ccs llamacpp "explain this code"
# Check which model is running
ccs llamacpp "what model are you?"
```
### Model-Specific Usage
```bash theme={null}
# Override model for this request
ANTHROPIC_MODEL=llama3-70b ccs llamacpp "complex system design"
# Use different quantization variant
ANTHROPIC_MODEL=qwen3-coder:q5 ccs llamacpp "debug this issue"
```
### Streaming and Output Control
```bash theme={null}
# Default streaming response
ccs llamacpp "write a function"
# Set temperature for creativity
ANTHROPIC_TEMPERATURE=0.8 ccs llamacpp "brainstorm ideas"
# Limit response length
ANTHROPIC_MAX_TOKENS=500 ccs llamacpp "summarize this"
```
## Troubleshooting
### Connection Refused
**Symptom:** `Error: connect ECONNREFUSED 127.0.0.1:8080`
**Causes & Solutions:**
1. **Server not running** — Start llama.cpp server in separate terminal
2. **Wrong port** — Check server is on 8080 or update ANTHROPIC\_BASE\_URL
3. **Firewall blocked** — Allow localhost connections
```bash theme={null}
# Verify server is listening
netstat -an | grep 8080
# or
curl http://127.0.0.1:8080/health
```
### Model Not Found or Slow Response
**Symptom:** Invalid model or very slow responses
**Solutions:**
```bash theme={null}
# Check available models on server
curl http://127.0.0.1:8080/models
# Switch to faster model
ANTHROPIC_MODEL=phi3-mini ccs llamacpp "quick task"
# Restart server with smaller model
./server -m /path/to/smaller-model.gguf
```
### Out of Memory
**Symptom:** `VRAM out of memory` or process crash
**Solutions:**
1. **Reduce context** — Limit with `-c 1024` when starting server
2. **Switch quantization** — Use Q4\_0 instead of Q5\_K\_M
3. **Reduce layers on GPU** — Use `-ngl 30` instead of `-ngl 99`
4. **Use smaller model** — Switch from 70B to 8B variant
```bash theme={null}
# Start with conservative GPU settings
./server -m /path/to/model.gguf \
--host 0.0.0.0 --port 8080 \
-ngl 30 \
-c 1024
```
### Port Already in Use
**Symptom:** `Address already in use`
**Solutions:**
```bash theme={null}
# Find what's using port 8080
lsof -i :8080
# Kill the process (if it's old llama.cpp instance)
kill -9
# Or use a different port
./server -m /path/to/model.gguf --host 0.0.0.0 --port 8081
# Then configure CCS
ANTHROPIC_BASE_URL=http://127.0.0.1:8081 ccs llamacpp "test"
```
## Performance Optimization
### GPU Acceleration
```bash theme={null}
# macOS with Metal GPU
./server -m model.gguf --host 0.0.0.0 --port 8080 -ngl 99
# Linux with CUDA
./server -m model.gguf --host 0.0.0.0 --port 8080 -ngl 99
# Disable GPU (CPU only)
./server -m model.gguf --host 0.0.0.0 --port 8080 -ngl 0
```
### Memory Management
| Setting | Impact | Use When |
| --------- | ----------------- | ----------------------------------- |
| `-ngl 99` | All layers on GPU | Plenty of VRAM (GPU-only inference) |
| `-ngl 30` | Partial offload | Limited VRAM (mixed CPU/GPU) |
| `-ngl 0` | CPU only | No GPU or testing |
| `-c 1024` | Small context | Limited RAM (\<8GB) |
| `-c 2048` | Default context | 8-16GB RAM |
| `-c 4096` | Large context | 16GB+ RAM |
### Batch Size and Threads
```bash theme={null}
# For faster inference with multiple users
./server -m model.gguf --host 0.0.0.0 --port 8080 \
-t 16 # Use more threads
-b 512 # Larger batch size for throughput
-ngl 99 # GPU acceleration
# For single user, lower latency
./server -m model.gguf --host 0.0.0.0 --port 8080 \
-t 4 # Fewer threads
-b 128 # Small batch for responsiveness
-ngl 99
```
## Cost Analysis
| Factor | Cost |
| ---------------- | ------------------------------------------ |
| **API costs** | \$0 (free) |
| **Hardware** | GPU (optional): \$200-800, or use CPU |
| **Electricity** | \~50-150W continuous (varies by model/GPU) |
| **Privacy** | Complete — data never leaves your machine |
| **Availability** | Offline-capable once model is downloaded |
## Common Questions
**Q: Can I use llama.cpp with older hardware?**
A: Yes, but it will be slow. CPU-only inference works on any machine. Consider smaller models like Phi-3 (2.3GB) which runs acceptably on older hardware.
**Q: How do I update models?**
A: Download new GGUF files and restart server with `-m /path/to/new-model.gguf`.
**Q: Can I run multiple llama.cpp servers for load balancing?**
A: Yes, start each on a different port and create separate CCS profiles pointing to each.
**Q: Is llama.cpp compatible with Claude API features?**
A: Basic chat only. Features like vision, web search, and extended thinking require Claude's official API.
## Storage Locations
| Path | Description |
| --------------------- | ------------------------------- |
| `~/Downloads/models/` | Default location for GGUF files |
| `~/.ccs/config.yaml` | CCS profile configuration |
| `llama.cpp/server` | Binary after build |
## Next Steps
Learn how to create and manage API profiles
Compare with Ollama (cloud/local models)
Explore all available models and providers
Common issues and solutions
# MiniMax Provider
Source: https://docs.ccs.kaitran.ca/providers/api/minimax
Access MiniMax M3 and M2 series models via API key authentication
# MiniMax Provider
Access MiniMax M3 and M2 series models with 1M context window through API key authentication. Ideal for long-context tasks requiring extended document analysis.
## Overview
The MiniMax provider enables Claude Code to use MiniMax's Anthropic-compatible API models. Requires an API key from the MiniMax platform.
**Provider Type:** API Preset (not OAuth)
**Command:** `ccs api create --preset mm`
**Supported Models:**
* MiniMax-M3 (default, 1M context)
* MiniMax-M2.5 (1M context)
* MiniMax-M2.5-lightning (fast variant, 1M context)
* MiniMax-M2.1 (1M context)
* MiniMax-M2.1-lightning (faster, 1M context)
* MiniMax-M2 (legacy)
## Setup
### Step 1: Get API Key
1. Visit [platform.minimax.io](https://platform.minimax.io)
2. Create an account or sign in
3. Navigate to API Keys section
4. Generate a new API key
### Step 2: Create Profile
```bash theme={null}
# Create MiniMax profile using preset
ccs api create mm --preset mm
# Enter your API key when prompted
```
### Step 3: Use Profile
```bash theme={null}
# Run with MiniMax
ccs mm "analyze this 500-page document"
# Interactive session
ccs mm
```
## Commands
### Basic Usage
```bash theme={null}
# Start session with MiniMax
ccs mm
# Run with prompt
ccs mm "your task here"
```
### Profile Management
```bash theme={null}
# List all API profiles
ccs api list
# Remove MiniMax profile
ccs api remove mm
```
## Configuration
Profile stored at: `~/.ccs/mm.settings.json`
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.minimax.io/anthropic",
"ANTHROPIC_AUTH_TOKEN": "your-api-key",
"ANTHROPIC_MODEL": "MiniMax-M3"
}
}
```
### Available Models
| Model | Context | Speed | Best For |
| ---------------------- | ----------- | -------- | ---------------------------------- |
| MiniMax-M3 | 1M tokens | Standard | Default, latest generation |
| MiniMax-M2.5 | 1M tokens | Standard | Deep analysis |
| MiniMax-M2.5-lightning | 1M tokens | Fast | Quick responses, latest generation |
| MiniMax-M2.1 | 1M tokens | Standard | Long documents, stable |
| MiniMax-M2.1-lightning | 1M tokens | Fast | Quick responses, large context |
| MiniMax-M2 | 200K tokens | Standard | Legacy, general use |
Model aliases are normalized automatically — `minimax-m2.5`, `MiniMax-M2.5`, and `minimax-M2.5` all resolve to the same model. CCS handles case and format differences transparently.
## Pricing
**Pay-as-you-go pricing** via MiniMax platform.
Refer to [MiniMax Pricing](https://platform.minimax.io/docs/guides/pricing-paygo) for current rates.
## Troubleshooting
### Invalid API Key
```bash theme={null}
# Verify your API key
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.minimax.io/anthropic/v1/models
```
### Rate Limiting
MiniMax applies rate limits based on your account tier. Upgrade your account at platform.minimax.io if you encounter 429 errors.
## Next Steps
Learn about custom API profiles
Configure via web interface
# Novita AI Provider
Source: https://docs.ccs.kaitran.ca/providers/api/novita
Access Novita AI through the built-in Anthropic-compatible CCS preset
# Novita AI Provider
Access Novita AI through CCS's built-in Anthropic-compatible preset. CCS ships the base URL, default profile name, and default model so you can go from API key to prompt quickly.
## Overview
| Field | Details |
| ------------------------ | --------------------------------- |
| **Preset ID** | `novita` |
| **Default Profile Name** | `novita` |
| **Default Model** | `deepseek/deepseek-v3.2` |
| **Base URL** | `https://api.novita.ai/anthropic` |
| **Auth Method** | API Key |
| **Category** | Alternative |
## Quick Start
```bash theme={null}
# Create profile with preset
ccs api create --preset novita
# Use default profile name
ccs novita "summarize this pull request"
```
## Authentication
Novita uses API key authentication.
Sign in to [novita.ai](https://novita.ai) and generate an API key for
Anthropic-compatible access.
```bash theme={null}
ccs api create --preset novita
```
Enter the profile name when prompted, or accept the default `novita`.
Then paste your API key.
```bash theme={null}
ccs novita "triage this production incident"
```
## Model Configuration
The preset defaults to `deepseek/deepseek-v3.2`, but you can override the model if Novita exposes another Anthropic-compatible model you want to use.
### Dashboard
```bash theme={null}
ccs config
# Navigate to API Profiles → Create → Novita AI
```
### Manual Configuration
Create `~/.ccs/novita.settings.json`:
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.novita.ai/anthropic",
"ANTHROPIC_AUTH_TOKEN": "your-novita-api-key",
"ANTHROPIC_MODEL": "deepseek/deepseek-v3.2"
}
}
```
Register it in `~/.ccs/config.yaml`:
```yaml theme={null}
profiles:
novita: ~/.ccs/novita.settings.json
```
## Commands Reference
```bash theme={null}
# Create profile
ccs api create --preset novita
# Use default profile name
ccs novita "your prompt"
# List API profiles
ccs api list
# Remove profile
ccs api remove novita
```
## Troubleshooting
### 401 Unauthorized
* Re-check the API key entered during setup
* Recreate the profile if needed: `ccs api remove novita && ccs api create --preset novita`
### Model Not Found
* Confirm the `ANTHROPIC_MODEL` value matches a Novita-supported Anthropic-compatible model
* Reset to the shipped default: `deepseek/deepseek-v3.2`
## Next Steps
Compare Novita with other API-key providers
See where Novita fits in the full CCS provider matrix
# Ollama Provider
Source: https://docs.ccs.kaitran.ca/providers/api/ollama
Local and cloud Ollama models with zero API costs and full privacy
# Ollama Provider
Run local open-source models via Ollama with zero API costs and complete privacy, or use Ollama Cloud for hosted models.
## Quick Start
```bash theme={null}
# Local Ollama (no API key needed)
ccs ollama "explain this code"
# Ollama Cloud (requires API key)
ccs ollama-cloud "refactor this function"
```
## Variants
### Ollama (Local)
Run models on your local machine with complete privacy and zero API costs.
**Configuration:**
* Base URL: `http://localhost:11434`
* Default model: `qwen3-coder`
* API key: Not required
* Context: 32K+ tokens
**Prerequisites:** Ollama must be installed and running locally.
### Ollama Cloud
Access Ollama's hosted models via their cloud API.
**Configuration:**
* Base URL: `https://ollama.com`
* Default models: `glm-4.7:cloud`, `minimax-m2.1:cloud`
* API key: Required from ollama.com
* Context: Varies by model
## Prerequisites
### Installing Ollama (Local)
Visit [ollama.com](https://ollama.com) and download for your platform
Follow platform-specific installation instructions
```bash theme={null}
ollama --version
```
```bash theme={null}
ollama pull qwen3-coder
```
### Ollama Cloud Setup
Sign up at [ollama.com](https://ollama.com)
Navigate to API settings and generate your API key
```bash theme={null}
ccs setup --preset ollama-cloud
# Enter your API key when prompted
```
## Configuration
### Local Ollama Setup
```bash theme={null}
# Via API profile preset
ccs api create --preset ollama
# Or direct shortcut
ccs ollama "test local model"
# Manual config in ~/.ccs/config.yaml
profiles:
ollama:
env:
ANTHROPIC_BASE_URL: "http://localhost:11434"
ANTHROPIC_MODEL: "qwen3-coder"
ANTHROPIC_AUTH_TOKEN: "ollama"
```
### Ollama Cloud Setup
```yaml theme={null}
# ~/.ccs/config.yaml
profiles:
ollama-cloud:
env:
ANTHROPIC_BASE_URL: "https://ollama.com"
ANTHROPIC_MODEL: "glm-4.7:cloud"
ANTHROPIC_AUTH_TOKEN: "YOUR_OLLAMA_CLOUD_API_KEY"
```
## Model Selection
### Popular Local Models
| Model | Size | Context | Use Case |
| ---------------- | ---- | ------- | -------------------- |
| `qwen3-coder` | 7B | 32K | Coding (recommended) |
| `deepseek-coder` | 6.7B | 16K | Code completion |
| `codellama` | 7B | 16K | Code generation |
| `mistral` | 7B | 8K | General purpose |
### Pulling Models
```bash theme={null}
# Install recommended coding model
ollama pull qwen3-coder
# List available models
ollama list
# Remove unused models
ollama rm model-name
```
### Cloud Models
| Model | Description |
| -------------------- | ------------------------ |
| `glm-4.7:cloud` | GLM via Ollama Cloud |
| `minimax-m2.1:cloud` | Minimax via Ollama Cloud |
## Usage Examples
### Local Ollama
```bash theme={null}
# Basic usage
ccs ollama "explain this function"
# Switch models
ANTHROPIC_MODEL=deepseek-coder ccs ollama "review this code"
# Custom temperature
ANTHROPIC_TEMPERATURE=0.7 ccs ollama "generate unit tests"
```
### Ollama Cloud
```bash theme={null}
# Use cloud variant
ccs ollama-cloud "debug this error"
# Specific cloud model
ANTHROPIC_MODEL=minimax-m2.1:cloud ccs ollama-cloud "optimize performance"
```
## Troubleshooting
### Connection Refused
**Symptom:** `Error: connect ECONNREFUSED 127.0.0.1:11434`
**Cause:** Ollama service not running
**Solution:**
```bash theme={null}
# Start Ollama service
ollama serve
# Or on macOS/Windows, launch Ollama app
```
### Model Not Found
**Symptom:** `Error: model 'qwen3-coder' not found`
**Cause:** Model not pulled locally
**Solution:**
```bash theme={null}
# Pull the model first
ollama pull qwen3-coder
# Verify installation
ollama list
```
### Slow Responses
**Symptom:** Long response times
**Causes & Solutions:**
* **CPU-only inference:** Use smaller model or add GPU support
* **Large model:** Switch to smaller variant (e.g., `qwen3-coder:3b`)
* **Insufficient RAM:** Close other apps, use quantized models
**Optimize performance:**
```bash theme={null}
# Use smaller quantized model
ollama pull qwen3-coder:q4_0
# Update model in config
ANTHROPIC_MODEL=qwen3-coder:q4_0 ccs ollama "test"
```
### Ollama Cloud API Errors
**Symptom:** `401 Unauthorized` or `403 Forbidden`
**Solution:**
```bash theme={null}
# Verify API key is correct
ccs config
# Navigate to ollama-cloud profile
# Re-enter API key
```
## Performance Tuning
### Context Length
```yaml theme={null}
# ~/.ccs/config.yaml
profiles:
ollama:
env:
ANTHROPIC_MAX_TOKENS: "32768" # Adjust based on model
```
### Concurrency
Ollama handles concurrent requests via queue. For better performance:
```bash theme={null}
# Increase parallel requests (Ollama config)
OLLAMA_NUM_PARALLEL=4 ollama serve
```
## Cost Information
| Variant | Cost | Privacy |
| -------------- | ----------------------- | -------------------------------------- |
| Ollama (Local) | **\$0** (hardware only) | Complete - data never leaves machine |
| Ollama Cloud | Varies by usage | Depends on Ollama Cloud privacy policy |
## Storage Locations
| Path | Description |
| ----------------------------- | -------------------------------------- |
| `~/.ollama/models/` | Downloaded model files |
| `~/.ccs/config.yaml` | CCS profile configuration |
| `~/.ccs/ollama.settings.json` | Model preferences (if using Dashboard) |
## Ollama vs llama.cpp
| Feature | Ollama | llama.cpp |
| ------------------- | ----------------------- | ---------------------------------- |
| **Model format** | Ollama format | GGUF (raw) |
| **Setup** | Easier (install + pull) | More manual |
| **Model selection** | Built-in model library | Any GGUF file |
| **Performance** | Good | Better (more optimization options) |
| **Community** | Large, many models | Smaller but growing |
| **Best for** | Getting started quickly | Fine-tuned control |
Use **Ollama** for quick setup with curated models. Use **llama.cpp** if you need specific GGUF models or advanced tuning.
## Next Steps
Configure custom Ollama endpoints
Alternative GGUF-based local inference
Manage models via web interface
Run Ollama on remote server
# Requesty Provider
Source: https://docs.ccs.kaitran.ca/providers/api/requesty
Access Requesty through the built-in OpenAI-compatible CCS preset
# Requesty Provider
Access Requesty through CCS's built-in OpenAI-compatible preset. CCS ships the
Requesty router URL, default profile name, and default model so you can create a
profile with only your Requesty API key.
## Overview
| Field | Details |
| ------------------------ | ------------------------------- |
| **Preset ID** | `requesty` |
| **Default Profile Name** | `requesty` |
| **Default Model** | `openai/gpt-4o-mini` |
| **Base URL** | `https://router.requesty.ai/v1` |
| **Auth Method** | API Key |
| **Category** | Alternative |
## Quick Start
```bash theme={null}
# Create profile with preset
ccs api create --preset requesty
# Use default profile name
ccs requesty "summarize this pull request"
```
## Authentication
Requesty uses API key authentication.
Sign in to [app.requesty.ai](https://app.requesty.ai/api-keys) and create a
Requesty API key.
```bash theme={null}
ccs api create --preset requesty
```
Accept the default profile name `requesty`, or enter another profile name.
Then paste your API key.
```bash theme={null}
ccs requesty "triage this issue"
```
## Model Configuration
The preset defaults to `openai/gpt-4o-mini`. Requesty model IDs include the
provider prefix, such as `openai/gpt-4o-mini`, so keep the full Requesty model
name when overriding the model.
### Dashboard
```bash theme={null}
ccs config
# Navigate to API Profiles -> Create -> Requesty
```
### Manual Configuration
Create `~/.ccs/requesty.settings.json`:
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://router.requesty.ai/v1",
"ANTHROPIC_AUTH_TOKEN": "your-requesty-api-key",
"ANTHROPIC_MODEL": "openai/gpt-4o-mini"
}
}
```
Register it in `~/.ccs/config.yaml`:
```yaml theme={null}
profiles:
requesty: ~/.ccs/requesty.settings.json
```
## Commands Reference
```bash theme={null}
# Create profile
ccs api create --preset requesty
# Use default profile name
ccs requesty "your prompt"
# List API profiles
ccs api list
# Remove profile
ccs api remove requesty
```
## Troubleshooting
### 401 Unauthorized
* Re-check the API key entered during setup
* Recreate the profile if needed: `ccs api remove requesty && ccs api create --preset requesty`
### Model Not Found
* Confirm the model ID uses Requesty's provider/model format, such as `openai/gpt-4o-mini`
* Reset to the shipped default: `openai/gpt-4o-mini`
## Next Steps
Compare Requesty with other API-key providers
Understand how CCS bridges OpenAI-compatible endpoints
# API Profiles
Source: https://docs.ccs.kaitran.ca/providers/concepts/api-profiles
Create custom API key profiles for any Anthropic-compatible endpoint
# API Profiles
API profiles let you use any Anthropic-compatible endpoint by configuring a base URL, API key, and model. No OAuth required.
## Available Presets
| Preset | Command | Default Model | Context | Category |
| --------------------- | ---------------- | ---------------------------- | ------- | ----------- |
| `anthropic` | `ccs anthropic` | `claude-sonnet-4-5-20250929` | 200K | Recommended |
| `alibaba-coding-plan` | `ccs albb` | `qwen3-coder-plus` | 1M | Recommended |
| `llamacpp` | `ccs llamacpp` | `llama3-8b` | Varies | Recommended |
| `ollama` | `ccs ollama` | `qwen3-coder` | 32K+ | Recommended |
| `openrouter` | `ccs openrouter` | 300+ models | Varies | Alternative |
| `novita` | `ccs novita` | `deepseek/deepseek-v3.2` | Varies | Alternative |
| `requesty` | `ccs requesty` | `openai/gpt-4o-mini` | Varies | Alternative |
| `minimax` | `ccs mm` | `MiniMax-M3` | 1M | Alternative |
| `glm` (built-in) | `ccs glm` | `glm-5.2` | 1M | Built-in |
| `km` (built-in) | `ccs km` | `kimi-for-coding` | Varies | Built-in |
## Creating Profiles
### Via Preset
```bash theme={null}
# Interactive wizard — prompts for name and API key
ccs api create --preset anthropic
ccs api create --preset alibaba-coding-plan
ccs api create --preset ollama
ccs api create --preset llamacpp
ccs api create --preset novita
ccs api create --preset openrouter
ccs api create --preset requesty
```
### Via Dashboard
```bash theme={null}
ccs config
# Navigate to: API Profiles → Create Profile → select preset
```
### Manual Settings File
Create `~/.ccs/.settings.json`:
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://your-endpoint.com/v1",
"ANTHROPIC_AUTH_TOKEN": "your-api-key",
"ANTHROPIC_MODEL": "model-name",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "model-name",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "model-name",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "model-name"
}
}
```
Register in `~/.ccs/config.yaml`:
```yaml theme={null}
profiles:
myprofile:
settings_file: ~/.ccs/myprofile.settings.json
```
All `env` values must be strings. Booleans or objects cause crashes on Windows PowerShell.
## CLIProxy Bridge
Use OAuth providers as API profiles via the CLIProxy bridge:
```bash theme={null}
ccs api create --cliproxy-provider gemini
ccs api create --cliproxy-provider codex
```
This creates an API profile that routes through the local CLIProxy instance, giving you API-key-style access to OAuth providers.
## Profile Lifecycle
```bash theme={null}
# List all API profiles
ccs api list
# Copy a profile with new name
ccs api copy glm glm-backup
# Export (without secrets by default)
ccs api export glm --out glm-export.json
ccs api export glm --out glm-export.json --include-secrets
# Import from file
ccs api import glm-export.json
ccs api import glm-export.json --name glm-restored
# Find unregistered settings files
ccs api discover
ccs api discover --register
# Remove profile
ccs api remove myprofile
```
## Extended Context (`--1m` flag)
Some profiles support a 1M token context window:
```bash theme={null}
# Enable 1M context for this session
ccs albb --1m "analyze entire codebase"
ccs km --1m "read all these files"
# Disable if auto-enabled
ccs albb --no-1m "quick task"
```
Profiles with 1M support: `alibaba-coding-plan`, `km`, `kimi`, `minimax`.
## Settings File Format
Full settings file with all optional fields:
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.example.com",
"ANTHROPIC_AUTH_TOKEN": "sk-your-key",
"ANTHROPIC_MODEL": "model-id",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "model-id",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "model-id",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "model-id",
"ANTHROPIC_DEFAULT_FABLE_MODEL": "model-id",
"ANTHROPIC_MAX_TOKENS": "8192",
"ANTHROPIC_THINKING_BUDGET": "8192"
}
}
```
## Common Profiles
### Z.AI GLM (`ccs glm`)
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
"ANTHROPIC_AUTH_TOKEN": "your_glm_api_key",
"ANTHROPIC_MODEL": "glm-5.2"
}
}
```
### Kimi for Coding (`ccs km`)
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.kimi.com/coding/",
"ANTHROPIC_AUTH_TOKEN": "your_kimi_api_key",
"ANTHROPIC_MODEL": "kimi-for-coding"
}
}
```
## Hybrid Workflow
Combine Claude subscriptions with API profiles for cost-optimized workflows:
```bash theme={null}
# Terminal 1: Strategic design with Claude (subscription)
ccs "design the authentication architecture"
# Terminal 2: Bulk implementation with GLM (API key, low cost)
ccs glm "implement all the services per the design"
# Terminal 3: Review with Codex (OAuth, no API key)
ccs codex "security review of the implementation"
```
## Next Steps
Direct API access with your Anthropic key
Qwen3 Coder with 1M context
Zero-cost local model inference
GGUF models with GPU acceleration
# Claude Accounts
Source: https://docs.ccs.kaitran.ca/providers/concepts/claude-accounts
Manage multiple Claude subscriptions with separate account profiles
# Claude Accounts
CCS lets you create multiple Claude account profiles such as `work`, `personal`,
and `team`. Different profiles normally use different Claude config directories.
Launching the same profile twice reuses the same directory and shared state.
This page covers **native account profiles**, which keep each account separate
with its own session history. If instead you want several Claude accounts to
act as one pool that auto-continues when an account hits its limit, see
[Account Pools](/features/pool). The two are different lanes and do not share
session history.
## How It Works
CCS uses `CLAUDE_CONFIG_DIR` to point Claude at a specific account profile
directory:
```
~/.ccs/instances/work/ # Work account
~/.ccs/instances/personal/ # Personal account
```
When you run `ccs work "task"`:
1. CCS points `CLAUDE_CONFIG_DIR` to `~/.ccs/instances/work/`
2. Claude loads that profile's credentials and state from the directory
3. The session reuses the `work` profile's account lane
In practice:
* `ccs work` + `ccs personal` normally use separate account directories
* `ccs work` + `ccs work` reuses one account directory
* Continuity inheritance can make different profile names reuse one account
directory on purpose
The recommended two-account route is to create both account profiles, then run
the account you want by name. This keeps credentials, tokens, and Claude's
`.anthropic` state isolated unless you explicitly opt in to shared continuity.
## Quick Start
```bash theme={null}
# Create accounts
ccs auth create work
ccs auth create personal
# Use them
ccs work "review this PR"
ccs personal "help with side project"
# Inspect isolation, settings sync, and resume lane
ccs auth show work
# Concurrent sessions (different terminals)
# Terminal 1: ccs work "implement feature"
# Terminal 2: ccs personal "research topic"
```
## Profile Management
```bash theme={null}
# List all accounts
ccs auth list
# Set default account (used when running bare `ccs`)
ccs auth default work
# Remove account
ccs auth remove personal --force
```
## Bare vs Non-Bare Profiles
| Mode | Description | Use Case |
| -------- | ------------------------------------------------------------ | ----------------- |
| Standard | Full account profile with its own `~/.ccs/instances//` | Most users |
| `--bare` | Thin profile that wraps the default Claude config dir | Minimal isolation |
Standard profiles are recommended for most use cases.
Non-bare profiles also reuse the shared CCS layout for `commands`, `skills`,
`agents`, `plugins`, `settings.json`, and user `CLAUDE.md`. On supported
platforms that is usually implemented with symlinks; on Windows, CCS may fall
back to copying when symlink creation fails.
For `settings.json`, the normal non-bare path is:
```text theme={null}
~/.ccs/instances//settings.json
-> ~/.ccs/shared/settings.json
-> ~/.claude/settings.json
```
That is settings sync, not token sync. Use `ccs auth show ` to confirm
whether the profile settings are currently shared with root Claude settings.
User instructions follow the same chain, with `~/.claude/CLAUDE.md` as the
canonical source. See [Shared Data](/features/config/shared-data#shared-claudemd)
for conflict recovery behavior.
## Context Groups (Opt-in Sharing)
By default each account keeps its own project context. Use shared context only
when you explicitly want multiple accounts to reuse the same project workspace.
```yaml theme={null}
# ~/.ccs/config.yaml
accounts:
alice:
context_mode: shared
context_group: "team-alpha"
bob:
context_mode: shared
context_group: "team-alpha" # Same group = shared context
charlie:
context_mode: shared
context_group: "team-beta" # Different group = separate project context
```
Accounts in the same `context_group` share:
* Project workspace via the `projects/` area
* Optional deeper continuity artifacts when you enable deeper continuity
Shared context is explicit opt-in. Use an explicit `context_group` when
configuring shared mode so the scope is obvious in both CLI and dashboard
workflows.
## Deeper Continuity
Enable cross-session memory persistence with the `--deeper-continuity` flag:
```bash theme={null}
ccs work --deeper-continuity "continue the refactor from yesterday"
```
This keeps additional continuity artifacts aligned for that shared context
group, including `session-env`, `file-history`, `shell-snapshots`, and `todos`.
For existing accounts, configure both accounts with shared mode and the same
group from Dashboard -> Accounts -> Sync, or recreate the intended lane with:
```bash theme={null}
ccs auth create work2 --share-context --context-group daily --deeper-continuity
```
## Concurrent Sessions
Running the **same profile** in two terminals is allowed, but both terminals
reuse the same `CLAUDE_CONFIG_DIR` and shared mutable state. Use different
profiles when you want stronger separation.
```bash theme={null}
# Separate state:
# Terminal 1
ccs work "implement auth"
# Terminal 2
ccs personal "write tests"
# Shared state on purpose:
# Terminal 1: ccs work "task A"
# Terminal 2: ccs work "task B"
```
## Instance Directory Structure
```
~/.ccs/instances/work/
├── .anthropic/ # Claude-managed metadata
├── session-env/ # Chat history and context
├── todos/ # Task lists
├── logs/ # Execution logs
├── file-history/ # Recent file context
├── shell-snapshots/ # Shell continuity artifacts
├── debug/ # Debug artifacts
├── commands/ # Shared link/copy in non-bare profiles
└── skills/ # Shared link/copy in non-bare profiles
```
## Default Account
```bash theme={null}
# Set work as default
ccs auth default work
# Now bare `ccs` uses the work account
ccs "review this code"
```
Before changing the default lane, back up the current native lane:
```bash theme={null}
ccs auth backup default
ccs auth default work
```
Setting the default only affects future plain `ccs` sessions. It does not import
old native `~/.claude/projects` history into the selected account profile.
## Resume the Correct Session Lane
Claude stores session history under the active `CLAUDE_CONFIG_DIR`. The
`ANTHROPIC_BASE_URL` only selects where requests are sent; changing it does not
move, merge, or change ownership of session history.
When you resume by session ID, use the account profile that owns the session:
```bash theme={null}
ccs work --resume ''
```
CCS checks the native lane and registered account profiles with valid names for
explicit session IDs. Discovery only trusts a normal `projects/` tree contained
inside its lane; symlinked project roots, project directories, or session files
that point elsewhere are ignored.
If the session belongs to another account, CCS prints that account's exact
resume command. Back up that lane before changing its setup:
```bash theme={null}
ccs auth backup work
```
If the session belongs to the native Claude lane and plain `ccs` still uses that
lane, resume normally:
```bash theme={null}
ccs --resume ''
```
If plain `ccs` is mapped to an account with `ccs auth default`, it searches that
account lane instead. CCS prints a command for the detected shell that clears
provider routing credentials, selects the native config directory, and resumes
with `claude`. Copy the command CCS prints; these examples show its shape:
```bash theme={null}
unset ANTHROPIC_BASE_URL; unset ANTHROPIC_AUTH_TOKEN; unset ANTHROPIC_API_KEY; export CLAUDE_CONFIG_DIR="$HOME/.claude"; claude --resume 00000000-0000-4000-8000-000000000000
```
```fish theme={null}
set -e ANTHROPIC_BASE_URL; set -e ANTHROPIC_AUTH_TOKEN; set -e ANTHROPIC_API_KEY; set -gx CLAUDE_CONFIG_DIR "$HOME/.claude"; claude --resume 00000000-0000-4000-8000-000000000000
```
```powershell theme={null}
Remove-Item Env:ANTHROPIC_BASE_URL -ErrorAction SilentlyContinue; Remove-Item Env:ANTHROPIC_AUTH_TOKEN -ErrorAction SilentlyContinue; Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue; $env:CLAUDE_CONFIG_DIR = "$HOME/.claude"; claude --resume 00000000-0000-4000-8000-000000000000
```
```batch theme={null}
set "ANTHROPIC_BASE_URL=" && set "ANTHROPIC_AUTH_TOKEN=" && set "ANTHROPIC_API_KEY=" && set "CLAUDE_CONFIG_DIR=%USERPROFILE%\.claude" && claude --resume 00000000-0000-4000-8000-000000000000
```
This explicit native route leaves the configured default account unchanged and
does not merge history.
If CCS cannot locate an explicit session ID, recover the original plain lane
first, back it up, then optionally make the intended account the default for
future plain `ccs` sessions:
```bash theme={null}
ccs -r
ccs auth backup default
ccs auth default work
```
Do not copy or combine `projects/` histories between account directories to fix
a resume mismatch. Resume from the owning lane instead.
## Cost
Each account requires its own Claude Pro ($20/month) or Max ($200/month)
subscription.
| Tier | Access | Cost |
| ---------- | -------------------------------------------------- | ----------- |
| Claude Pro | Claude Opus 4.6, Sonnet 4.6, Sonnet 4.5, Haiku 4.5 | \$20/month |
| Claude Max | All Pro models with extended usage limits | \$200/month |
## Next Steps
Combine Claude accounts with API key providers
Compare Claude accounts vs OAuth providers
Config file format for accounts
Step-by-step multi-account setup guide
# Provider Overview
Source: https://docs.ccs.kaitran.ca/providers/concepts/overview
Compare CCS providers: CLIProxy OAuth providers, Claude accounts, and API profiles
# Provider Overview
CCS supports CLIProxy OAuth providers plus Claude accounts and API
profiles (including Alibaba Coding Plan, OpenRouter, Novita, GLM, MiniMax, and
more). This guide helps you choose the right provider for your needs.
## Provider Categories
**OAuth Providers** - Zero API keys, browser callback, device-code, or browser-polling login
Perfect for beginners and quick setup
**Multiple Subscriptions** - Isolated Claude instances
Work/personal separation, concurrent sessions
**Direct API Access** - Bring your own keys
Custom endpoints, self-hosted models
## Quick Decision Guide
**Choose your path:**
**Recommended:** Codex for browser OAuth, or Kiro if you want a free Builder ID path
```bash theme={null}
ccs codex "your first query"
# Browser opens → Sign in → Start coding
```
* No API keys needed
* Good baseline for your first session
* Auto token refresh on supported providers
* Multi-account support
**Best for:** Multiple Claude subscriptions
```bash theme={null}
ccs auth create work
ccs auth create personal
# Use both simultaneously in different terminals
```
* Work/personal isolation
* Concurrent sessions
* Team collaboration
* Existing subscription leverage
**Best for:** Self-hosted models, custom APIs
```bash theme={null}
ccs config
# Add API profile with custom endpoint + API key
```
* Full control over endpoints
* Self-hosted model support
* Custom headers/authentication
* Built-in presets such as OpenRouter, Novita, and Alibaba
## Authentication Methods Comparison
### Browser Callback vs Device Code vs Browser Polling
| Feature | Browser Callback | Device Code | Browser Polling |
| -------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Setup** | Browser opens and returns through a local callback | Manual URL/code or device login | Browser opens and CCS polls upstream auth completion |
| **Headless Servers** | Usually pair with `--headless` or `--paste-callback` | Native support | Limited; best on desktop/browser-capable machines |
| **Providers** | Gemini, Codex, Antigravity, iFlow, Claude, GitLab | Kimi, Kiro (default), Kilo, Qoder, xAI (Grok), deprecated GHCP compatibility | Cursor, CodeBuddy |
| **Best For** | Local development, desktop | CI/CD, remote servers | Provider-specific browser-driven flows |
Kiro also supports optional auth-code and IDC flows via `--kiro-auth-method`.
GitLab Duo also supports PAT login via `--gitlab-token-login`.
**Example: Browser Callback Flow**
```bash theme={null}
ccs codex "task"
# → Browser opens → Provider login → Token cached → Session starts
```
**Example: Device Code Flow**
```bash theme={null}
ccs xai --auth
# → Device code displayed → Copy URL/code → Token cached
```
**Example: Browser Polling Flow**
```bash theme={null}
ccs cursor --auth
# → Browser opens → Upstream auth completes → CCS detects the session
```
## All Providers Comparison
### Providers At A Glance
**Google Gemini** - Google OAuth route
| Feature | Details |
| ----------------- | ----------------------------------------------------------- |
| **Models** | Gemini 3 Pro (High/Preview), Gemini 2.5 Pro, Gemini 3 Flash |
| **Free Tier** | ✅ Yes (Gemini 2.5 Pro) |
| **Auth Method** | Browser OAuth (Google SSO) |
| **Multi-Account** | ✅ Yes (email-based) |
| **Model Picker** | ✅ Interactive `--config` |
| **Quota Display** | ✅ Auto project rotation |
| **Token Refresh** | ✅ Automatic (CLIProxy-managed) |
| **Best For** | Beginners, free tier users, fast responses |
For command examples and setup flow, open the dedicated Gemini provider page.
[Full Documentation →](/providers/oauth/gemini)
**Kiro (AWS)** - AWS device code by default, optional browser auth flows
| Feature | Details |
| ----------------- | ---------------------------------------------------------------- |
| **Models** | Amazon CodeWhisperer (AWS) |
| **Free Tier** | ✅ Yes (Builder ID) |
| **Auth Method** | AWS device code by default, plus optional auth-code/Google flows |
| **Multi-Account** | ✅ Yes (filename-based) |
| **Model Picker** | ❌ No (single model) |
| **Token Import** | ✅ From Kiro IDE |
| **Browser Mode** | Normal (default), incognito disabled on Linux |
| **Best For** | AWS users, Kiro IDE users |
```bash theme={null}
ccs kiro "your query"
ccs kiro --import # Import from Kiro IDE
ccs kiro --no-incognito # Normal browser (Linux fix)
```
[Full Documentation →](/providers/oauth/kiro)
**GitHub Copilot (GHCP)** - Deprecated device-code OAuth compatibility via CLIProxy
GitHub Copilot is kept for existing setups only. GitHub usage-based Copilot
billing begins June 1, 2026; prefer Codex or another active provider for
new work.
| Feature | Details |
| ----------------- | ----------------------------------------------------- |
| **Models** | GitHub Copilot models |
| **Free Tier** | ❌ No (requires subscription) |
| **Auth Method** | Device code OAuth |
| **Multi-Account** | ✅ Yes (GitHub username) |
| **Device Code** | ✅ Built-in default flow |
| **Quota Display** | ✅ Yes (`--quota`) |
| **Best For** | Existing Copilot setups that still need compatibility |
```bash theme={null}
# Start GHCP and complete the device-code prompt
ccs ghcp "your query"
# Check quota
ccs ghcp --quota
```
[Full Documentation →](/providers/oauth/ghcp)
**OpenAI Codex** - OpenAI coding models via OAuth
| Feature | Details |
| ----------------- | ------------------------------------------------------------------------- |
| **Models** | GPT-5 Codex, GPT-5 Codex Mini, GPT-5.2 Codex, GPT-5.3 Codex, GPT-5.4 |
| **Free Tier** | ✅ Cross-plan-safe models available; paid plans unlock paid-only model IDs |
| **Auth Method** | Browser OAuth (OpenAI) |
| **Multi-Account** | ✅ Yes (email-based) |
| **Model Picker** | ✅ Interactive `--config` |
| **Best For** | OpenAI users who want Codex via OAuth |
```bash theme={null}
ccs codex "your query"
ccs codex --auth --add # Add account
```
[Full Documentation →](/providers/oauth/codex)
**xAI (Grok)** - CLIProxy device-code OAuth
| Feature | Details |
| ----------------- | -------------------------------------------- |
| **Provider ID** | `xai`; `grok` is a CLI alias |
| **Models** | Live catalog with cached and static fallback |
| **Auth Method** | Device code OAuth; no callback port |
| **Multi-Account** | ✅ Yes (email or filename-derived ID) |
| **Model Picker** | ✅ Interactive `--config` |
| **Quota Display** | ❌ Not supported |
| **Token Refresh** | ✅ CLIProxy-managed |
```bash theme={null}
ccs xai --auth
ccs xai --accounts
ccs grok "your query" # alias for ccs xai
```
[Full Documentation →](/providers/oauth/xai)
**Kimi (Moonshot)** - Device-code OAuth via CLIProxy
| Feature | Details |
| ----------------- | ----------------------------------------------- |
| **Models** | Kimi K2.5, Kimi K2 Thinking, Kimi K2 |
| **Auth Method** | Device code OAuth |
| **Multi-Account** | ✅ Yes (email-based) |
| **Model Picker** | ✅ Interactive `--config` |
| **Token Refresh** | ✅ Auto via CLIProxy |
| **Best For** | Moonshot users who want Kimi without an API key |
```bash theme={null}
ccs kimi "your query"
ccs kimi --accounts
ccs kimi --use work
```
[Full Documentation →](/providers/oauth/kimi)
**Antigravity (AGY)** - Subscription multi-model route
| Feature | Details |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Models** | Claude Opus 4.6 Thinking (default), Claude Opus 4.6, Claude Sonnet 4.6 Thinking, Claude Sonnet 4.6, Gemini 3 Pro |
| **Free Tier** | ❌ No (subscription required) |
| **Auth Method** | Browser OAuth |
| **Multi-Account** | ✅ Yes (email-based) |
| **Model Picker** | ✅ Interactive `--config` |
| **Best For** | Premium users, multi-model access |
For command examples and setup flow, open the dedicated Antigravity provider page.
[Full Documentation →](/providers/oauth/agy)
**Claude (Anthropic)** - Direct Anthropic OAuth
| Feature | Details |
| ----------------- | ------------------------------------------- |
| **Models** | Claude models via Anthropic |
| **Free Tier** | ❌ No (requires subscription) |
| **Auth Method** | Browser OAuth (Anthropic SSO) |
| **Multi-Account** | ✅ Yes (email-based) |
| **Model Picker** | ✅ Interactive `--config` |
| **Token Refresh** | ✅ Auto |
| **Best For** | Anthropic subscribers, direct Claude access |
```bash theme={null}
ccs claude "your query"
ccs claude --auth --add # Add account
```
[Full Documentation →](/providers/oauth/claude)
**Qwen3 Coder** - Use the API-key Alibaba Coding Plan route
| Feature | Details |
| ----------------- | ----------------------------------- |
| **Models** | Qwen3 Coder Plus, Qwen3 Coder Flash |
| **Free Tier** | ❌ No (subscription required) |
| **Auth Method** | API key |
| **Multi-Account** | Profile-based |
| **Model Picker** | ❌ No (single model) |
| **Best For** | Specialized coding tasks |
```bash theme={null}
ccs albb "your query"
```
[Full Documentation →](/providers/api/alibaba)
**iFlow** - Various models
| Feature | Details |
| ----------------- | ---------------------------- |
| **Models** | Multiple models available |
| **Free Tier** | ❌ No (subscription required) |
| **Auth Method** | Browser OAuth |
| **Multi-Account** | ✅ Yes (email-based) |
| **Model Picker** | Check provider for details |
| **Best For** | iFlow subscribers |
```bash theme={null}
ccs iflow "your query"
```
[Full Documentation →](/providers/oauth/iflow)
**MiniMax** - Long-context specialist
| Feature | Details |
| ------------------ | -------------------------------------------- |
| **Models** | MiniMax with 1M token context |
| **Free Tier** | ❌ No (API key required) |
| **Auth Method** | API Key (via API Profiles) |
| **Multi-Account** | ✅ Yes (profile-based) |
| **Model Picker** | ❌ No (single model) |
| **Context Window** | 1M tokens (largest available) |
| **Best For** | Large codebase analysis, document processing |
```bash theme={null}
# Quick setup with preset
ccs api create mm --preset mm
# Use profile
ccs mm "analyze large document"
```
[Full Documentation →](/providers/api/minimax)
**Alibaba Coding Plan** - Qwen3 Coder via API key
| Feature | Details |
| ------------------ | ------------------------------------------------ |
| **Models** | qwen3-coder-plus (default), qwen3-coder-flash |
| **Free Tier** | ❌ No (API key required) |
| **Auth Method** | API Key (`sk-sp-...`) |
| **Multi-Account** | ✅ Yes (profile-based) |
| **Context Window** | 1M tokens |
| **Best For** | Cost-effective coding tasks, Alibaba Cloud users |
```bash theme={null}
# Quick setup with preset
ccs api create --preset alibaba-coding-plan
# Use default profile name
ccs albb "implement this feature"
```
[Full Documentation →](/providers/api/alibaba)
**Novita AI** - Anthropic-compatible hosted endpoint
| Feature | Details |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Models** | Default preset uses `deepseek/deepseek-v3.2`; other Novita-supported Anthropic-compatible models can be configured manually |
| **Free Tier** | ❌ No (API key required) |
| **Auth Method** | API Key |
| **Multi-Account** | ✅ Yes (profile-based) |
| **Model Picker** | ✅ Via API Profile editor |
| **Best For** | Fast hosted setup when you want a built-in Anthropic-compatible preset |
```bash theme={null}
ccs api create --preset novita
ccs novita "summarize this incident"
```
[Full Documentation →](/providers/api/novita)
**Requesty** - OpenAI-compatible LLM gateway
| Feature | Details |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| **Models** | Default preset uses `openai/gpt-4o-mini`; other Requesty provider/model IDs can be configured manually |
| **Free Tier** | ❌ No (API key required) |
| **Auth Method** | API Key |
| **Multi-Account** | ✅ Yes (profile-based) |
| **Model Picker** | ✅ Via API Profile editor |
| **Best For** | Routing through Requesty's OpenAI-compatible model gateway |
```bash theme={null}
ccs api create --preset requesty
ccs requesty "summarize this incident"
```
[Full Documentation →](/providers/api/requesty)
### Claude Accounts
Run multiple Claude subscriptions simultaneously with separate account profiles:
| Feature | Details |
| ----------------------- | ------------------------------------------------------------------------- |
| **Setup** | `ccs auth create ` |
| **Multi-Account** | ✅ Unlimited profiles |
| **Concurrent Sessions** | ✅ Different profiles use separate default account directories |
| **Session Isolation** | ✅ Separate by default; reusing the same profile reuses the same directory |
| **Subscription** | Requires existing Claude Pro/Team |
| **Best For** | Work/personal separation, team collaboration |
**Example:**
```bash theme={null}
# Create profiles
ccs auth create work
ccs auth create personal
# Use simultaneously
ccs work "implement feature" # Terminal 1
ccs personal "side project" # Terminal 2 (concurrent)
```
[Full Documentation →](/providers/concepts/claude-accounts)
### API Profiles
Direct API access with custom endpoints and keys:
| Feature | Details |
| ----------------------- | ----------------------------------------------- |
| **Setup** | `ccs config` → Add API profile |
| **Custom Endpoints** | ✅ Full control |
| **Self-Hosted Models** | ✅ Supported |
| **API Key Management** | Manual (you provide keys) |
| **Model Configuration** | Provider-dependent |
| **Best For** | Custom APIs, self-hosted models, advanced users |
**Example:**
```bash theme={null}
# Configure via dashboard
ccs config
# Add profile:
# - Name: myapi
# - Endpoint: https://api.example.com/v1/chat
# - API Key: sk-...
# - Model: custom-model-name
# Use profile
ccs myapi "your query"
```
[Full Documentation →](/providers/concepts/api-profiles)
### Additional Current CLIProxy OAuth Providers
These providers are current and supported in CCS today even though they arrived
after the older nine-provider docs pass:
| Provider | Auth Model | Backend | Notes | Docs |
| ---------- | -------------------- | -------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------ |
| xAI (Grok) | Device code | `original` or `plus` | canonical `xai`; `grok` is a CLI alias | [xAI Provider](/providers/oauth/xai) |
| Cursor | Browser polling | `plus` | current `ccs cursor` provider path; different from the deprecated local bridge | [Cursor Provider](/providers/oauth/cursor) |
| GitLab Duo | Browser OAuth or PAT | `plus` | supports `--gitlab-token-login` and `--gitlab-url` | [GitLab Duo Provider](/providers/oauth/gitlab) |
| CodeBuddy | Browser polling | `plus` | auth and routing via CLIProxy | [CodeBuddy Provider](/providers/oauth/codebuddy) |
| Kilo AI | Device code | `plus` | CLIProxy-backed device-code provider | [Kilo AI Provider](/providers/oauth/kilo) |
| Qoder | Device code | `plus` | Qoder coding provider with interactive model picker | [Qoder Provider](/providers/oauth/qoder) |
## Feature Matrix
### All Providers Feature Comparison
| Provider | Free Tier | Multi-Account | Model Picker | Quota Display | Token Refresh | Headless Mode |
| ----------------------- | ------------------ | ------------- | ------------ | ------------- | ------------------ | -------------- |
| **Gemini** | ✅ | ✅ | ✅ | ✅ | ✅ Proactive | ✅ |
| **Kiro** | ✅ | ✅ | ❌ | ❌ | ✅ Auto | ✅ |
| **Kimi** | Varies | ✅ | ✅ | ❌ | ✅ Auto | ✅ Device Code |
| **GHCP (deprecated)** | ❌ | ✅ | ❌ | ✅ | ✅ Auto | ✅ Device Code |
| **Codex** | ✅ Limited | ✅ | ✅ | ✅ | ✅ Auto | ✅ |
| **xAI (Grok)** | Provider-dependent | ✅ | ✅ | ❌ | ✅ CLIProxy-managed | ✅ Device Code |
| **Antigravity** | ❌ | ✅ | ✅ | ✅ | ✅ Auto | ✅ |
| **Claude** | ❌ | ✅ | ✅ | ❌ | ✅ Auto | ✅ |
| **iFlow** | ❌ | ✅ | ❌ | ❌ | ✅ Auto | ✅ |
| **Cursor** | Varies | ✅ | ❌ | ❌ | ✅ Auto | Browser-driven |
| **GitLab Duo** | Varies | ✅ | ❌ | ❌ | ✅ Auto | ✅ |
| **CodeBuddy** | Varies | ✅ | ❌ | ❌ | ✅ Auto | Browser-driven |
| **Qoder** | Varies | ✅ | ✅ | ❌ | ❌ Re-auth | ✅ Device Code |
| **Kilo AI** | Varies | ✅ | ❌ | ❌ | Manual re-auth | ✅ Device Code |
| **MiniMax** | ❌ | ✅ | ❌ | ❌ | Manual | ✅ |
| **Alibaba Coding Plan** | ❌ | ✅ | ❌ | ❌ | Manual | ✅ |
| **Novita AI** | ❌ | ✅ | ✅ | ❌ | Manual | ✅ |
| **Claude Accounts** | ❌ | ✅ | ❌ | ❌ | N/A | N/A |
| **API Profiles** | Varies | ✅ | Varies | ❌ | Manual | ✅ |
### Authentication Features
| Provider | Auth Method | Account ID | Token Import | Browser Control |
| ----------------------- | ----------------------------------- | ------------------------ | ------------ | ------------------------------ |
| **Gemini** | Browser OAuth | Email | ❌ | Incognito default |
| **Kiro** | Device code + optional browser auth | Filename | ✅ IDE | Normal (no incognito) |
| **Kimi** | Device Code | Email | ❌ | N/A |
| **GHCP (deprecated)** | Device Code | GitHub username | ❌ | N/A |
| **Codex** | Browser OAuth | Email | ❌ | Incognito default |
| **xAI (Grok)** | Device Code | Email / filename-derived | ❌ | No callback |
| **Antigravity** | Browser OAuth | Email | ❌ | Incognito default |
| **Claude** | Browser OAuth | Email | ❌ | Incognito default |
| **iFlow** | Browser OAuth | Email | ❌ | Incognito default |
| **Cursor** | Browser polling | Provider-managed | ❌ | No local callback |
| **GitLab Duo** | Browser OAuth or PAT | GitLab user | ✅ PAT | Paste-callback for self-hosted |
| **CodeBuddy** | Browser polling | Provider-managed | ❌ | No local callback |
| **Kilo AI** | Device Code | Provider-managed | ❌ | N/A |
| **MiniMax** | API Key | Profile name | ❌ | N/A |
| **Alibaba Coding Plan** | API Key | Profile name | ❌ | N/A |
| **Novita AI** | API Key | Profile name | ❌ | N/A |
| **Claude Accounts** | OAuth (Claude) | Profile name | ❌ | N/A |
| **API Profiles** | API Key | Profile name | ❌ | N/A |
## Provider Selection Guide
### By Use Case
**→ Codex or Kiro**
* No API keys needed
* Good first-run coverage in CCS docs
* Codex works well for browser OAuth
* Kiro offers a free Builder ID route
**→ Claude Accounts**
* Isolated sessions
* Concurrent use
* Separate subscriptions
* Professional workflow
**→ GHCP** (deprecated compatibility, device code)
* Headless-friendly
* No browser needed
* Scriptable auth
* Quota management
**→ Kiro**
* CodeWhisperer via AWS Builder ID
* Device-code friendly
* No paid subscription required
**→ Claude Accounts or Codex**
* Claude Pro/Max account workflows
* Codex paid-plan model access
* Strong review and implementation coverage
* Clear first-party documentation
**→ MiniMax**
* 1M token context window
* Large codebase analysis
* Document processing
* API key authentication
**→ API Profiles**
* Custom endpoints
* Local LLMs
* Full control
* Privacy-focused
**→ Kiro**
* CodeWhisperer integration
* AWS Builder ID device code by default
* IDE token import
* Free Builder ID
**→ Codex**
* Cross-plan-safe GPT-5 Codex defaults
* GPT-5.3 Codex / GPT-5.2 Codex when available
* OpenAI ecosystem
**→ Alibaba Coding Plan**
* Qwen3 Coder Plus/Flash
* 1M token context
* $1.00/$5.00 per M tokens
* `ccs api create --preset alibaba`
### By Authentication Preference
**Prefer Browser OAuth?**
* Gemini, Codex, Antigravity, iFlow, Claude, GitLab Duo, plus optional Kiro auth-code / Google flows
**Prefer Device Code?**
* Kimi, Kiro (default), Kilo AI, Qoder, xAI (Grok), deprecated GHCP compatibility
**Prefer Browser Polling?**
* Cursor, CodeBuddy
**Prefer PAT / Token Login?**
* GitLab Duo (`--gitlab-token-login`)
**Prefer API Keys?**
* API Profiles
**Prefer No External Auth?**
* Claude Accounts (uses Claude CLI's built-in OAuth)
### By Cost Model
**Free Tier Available:**
* **Gemini** - Gemini 2.5 Pro (free Google account)
* **Kiro** - CodeWhisperer (AWS Builder ID)
**Requires Subscription:**
* **Gemini 3 Pro** - Paid Google account
* **GHCP** - Deprecated GitHub Copilot compatibility for existing setups
* **Codex paid / preview models** - Paid Codex plan required for `gpt-5.5` and `gpt-5.3-codex`; `gpt-5.3-codex-spark` is research preview for ChatGPT Pro subscribers
* **Antigravity** - Subscription
* **Claude** - Anthropic subscription
* **iFlow** - Subscription
**Use Existing Subscription:**
* **Claude Accounts** - Claude Pro/Team
**Bring Your Own:**
* **API Profiles** - You manage costs
* **Alibaba Coding Plan** - Qwen3 Coder (from \$0.30/M input)
* **Novita AI** - Anthropic-compatible preset with hosted routing
* **Requesty** - OpenAI-compatible gateway preset
* **OpenRouter** - 300+ models, pay per use
## Multi-Account Management
All OAuth providers support multiple accounts:
**Codex, Gemini, Antigravity, iFlow**
```bash theme={null}
# Add account
ccs codex --auth --add
# List accounts
ccs codex --accounts
# Output:
# * john (john@gmail.com) - default
# work (alice@company.com)
# Switch account
ccs codex --use work
# Rename account
ccs codex --nickname personal
```
**Account ID:** Email prefix (`john@gmail.com` → `john`)
**GitHub Copilot (deprecated compatibility)**
```bash theme={null}
# Add account
ccs ghcp --auth --add
# List accounts
ccs ghcp --accounts
# Output:
# * kaitranntt (GitHub) - default
# company-bot (GitHub)
# Switch account
ccs ghcp --use company-bot
```
**Account ID:** GitHub username
**Kiro (AWS CodeWhisperer)**
```bash theme={null}
# Add account
ccs kiro --auth --add
# List accounts
ccs kiro --accounts
# Output:
# * github-ABC123 (default)
# github-XYZ789
# Switch account
ccs kiro --use github-XYZ789
```
**Account ID:** Extracted from token filename
**xAI (Grok)**
```bash theme={null}
ccs xai --accounts
ccs xai --use
```
**Account ID:** Email when present in token metadata; otherwise a stable ID
derived from the `xai-*.json` filename.
**Cursor, GitLab Duo, CodeBuddy, Kilo AI**
```bash theme={null}
ccs cursor --auth
ccs cursor --accounts
ccs cursor --use
ccs gitlab --auth --gitlab-token-login
ccs codebuddy --auth
ccs kilo --auth
```
**Account ID:** Derived from the upstream provider session or token metadata.
**Claude Accounts**
```bash theme={null}
# Create profiles
ccs auth create work
ccs auth create personal
# List profiles
ccs auth list
# Use profiles
ccs work "task"
ccs personal "task"
# Set default
ccs auth default work
```
**Account ID:** Profile name (custom)
## Storage Locations
All providers store data in `~/.ccs/`:
```
~/.ccs/
├── cliproxy/
│ ├── auth/ # OAuth tokens
│ │ ├── gemini-john@gmail.com.json
│ │ ├── kiro-github-ABC123.json
│ │ ├── ghcp-kaitranntt.json
│ │ ├── xai-subject-one.json
│ │ └── ...
│ ├── providers/
│ │ └── cursor.settings.json # dedicated Cursor provider settings
│ ├── accounts.json # Account registry (all OAuth providers)
│ └── config.yaml # CLIProxy configuration
├── instances/ # Claude account profiles
│ ├── work/
│ └── personal/
├── gemini.settings.json # Provider-specific settings
├── agy.settings.json
├── xai.settings.json
└── config.yaml # Global CCS config
```
## Common Commands (All Providers)
### Authentication
```bash theme={null}
# Initial auth (browser opens)
ccs --auth
# Add new account (preserves existing)
ccs --auth --add
# Logout (clear tokens)
ccs --logout
# Headless mode (manual URL)
ccs --headless
```
### Account Management
```bash theme={null}
# List all accounts
ccs --accounts
# Switch default account
ccs --use
# Rename current account
ccs --nickname
```
### Execution
```bash theme={null}
# Execute query (interactive session)
ccs "your prompt"
# One-shot mode
ccs "quick question" --one-shot
```
### Configuration
```bash theme={null}
# Provider-specific config (supported providers only)
ccs codex --config
ccs claude --config
ccs xai --config
# Global dashboard
ccs config
```
## Provider-Specific Features
### Gemini Unique Features
* ✅ Automatic CLIProxy-managed token refresh
* ✅ Auto project rotation on quota exceeded
* ✅ Interactive model picker (4 models)
* ✅ Free tier (Gemini 2.5 Pro)
### Kiro Unique Features
* ✅ Token import from Kiro IDE (`--import`)
* ✅ Browser mode control (`--no-incognito`)
* ✅ AWS Builder ID device code by default
* ✅ Free tier (Builder ID)
### GHCP Deprecated Compatibility Features
* ✅ Built-in device-code OAuth flow
* ✅ Quota display (`--quota`)
* ✅ Device code for headless servers
* ✅ GitHub integration
### More Current CLIProxy Providers
* ✅ **Cursor** provider path lives under `ccs cursor --auth`
* ✅ **GitLab Duo** supports browser OAuth and PAT login
* ✅ **CodeBuddy** is supported as a browser-polling provider
* ✅ **Kilo AI** is supported as a device-code provider
* ✅ **Qoder** is supported as a device-code provider with model picker
* ✅ **xAI (Grok)** is supported as a device-code provider; `grok` is its CLI alias
### Antigravity Unique Features
* ✅ Multi-model access (Claude + Gemini)
* ✅ Claude Opus 4.6 Thinking (latest flagship)
* ✅ Claude Sonnet 4.6 Thinking
* ✅ Interactive model picker
### Claude Accounts Unique Features
* ✅ Concurrent sessions (different profiles)
* ✅ Separate account directories by default
* ✅ Unlimited profiles
* ✅ Work/personal separation
## Next Steps
Free tier, proactive refresh, 4 models
AWS CodeWhisperer, IDE import, free tier
Compatibility path, device code, quota display
GPT-5 Codex defaults, paid-plan models, plan-aware fallbacks
Device-code OAuth, `xai` provider ID, `grok` CLI alias
Claude Opus 4.6 Thinking, multi-model picker
Direct Anthropic OAuth access
Qwen3 Coder via API key
Various models available
Current CLIProxy Cursor provider path
Browser OAuth or PAT login
Tencent CodeBuddy provider
CLIProxy device-code provider
Qoder coding provider
1M context window, long-context tasks
Anthropic-compatible preset, default `deepseek/deepseek-v3.2`
OpenAI-compatible gateway, default `openai/gpt-4o-mini`
Multiple subscriptions, concurrent sessions
Custom endpoints, self-hosted models
Qwen3 Coder, 1M context, cost-effective
## FAQ
**Yes!** Different providers are the simplest way to avoid reusing the same provider or proxy lane:
```bash theme={null}
# Terminal 1
ccs codex "task A"
# Terminal 2
ccs kimi "task B"
# No conflicts
```
**Kiro or Codex** - pick the one that matches the account you already have:
```bash theme={null}
ccs codex "your first query"
# Browser opens → Provider login → Start coding
```
**Yes!** All OAuth providers support multi-account with instant switching:
```bash theme={null}
ccs codex --use work # Switch to work account
ccs codex --use personal # Switch to personal
# No re-auth needed
```
* **GHCP** - Deprecated compatibility with built-in device-code flow
* **xAI (Grok)** - Native device-code OAuth (`ccs xai --auth --headless`)
* **All OAuth Providers** - Headless mode (`--headless`, copy URL manually)
* **API Profiles** - No browser needed (API keys only)
**Yes** for OAuth providers - tokens sync automatically if you:
1. Copy `~/.ccs/cliproxy/auth/` to new machine
2. Re-authenticate on new machine (tokens specific to each machine)
**Better:** Re-auth on each machine for security.
* **Different providers:** Concurrent; usually the easiest way to keep sessions separate
* **Same provider, different accounts:** Concurrent (if supported by backend)
* **Claude Accounts:** Concurrent with different profiles; same profile is allowed but reuses the same account directory
* **Same provider, same account:** Provider-specific; may reuse the same provider/proxy session instead of giving full isolation
# Antigravity Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/agy
Access Claude Opus 4.6 and Gemini 3 Pro via Antigravity OAuth
# Antigravity Provider
Access premium AI models (Claude Opus 4.6, Claude Sonnet 4.6, Gemini 3 Pro) through Antigravity's OAuth-based platform. Features real-time quota monitoring and multi-account support.
## Overview
Antigravity provides access to Claude and Gemini models through a subscription service. CCS integrates seamlessly with OAuth authentication and real-time quota tracking.
**Provider Identifier:** `agy`
**Command:** `ccs agy`
**Supported Models:**
* Claude Opus 4.6 Thinking (default) - Latest flagship with extended thinking
* Claude Opus 4.6 - Latest flagship standard
* Claude Sonnet 4.6 Thinking - Balanced with extended thinking
* Claude Sonnet 4.6 - Fast and capable
* Gemini 3 Pro - Google's latest model via Antigravity
* Interactive model picker via `--config`
Claude 4.5 model IDs are deprecated in AGY as of v7.51. Existing sessions referencing 4.5 model IDs are automatically migrated to their 4.6 equivalents. Re-run `ccs doctor --fix` if you see 502 errors after upgrading.
Do not reuse the same Google account for both `ccs gemini` and `ccs agy`. Using one Google account across both providers causes token conflicts and authentication failures (see issue #509). Use separate Google accounts for each provider.
## Authentication
### First-Time Setup
```bash theme={null}
# Run Antigravity for the first time
ccs agy "analyze this code"
# Browser opens automatically
# → Complete OAuth login
# → Token cached at ~/.ccs/cliproxy/auth/
# → Future runs require no re-auth
```
**Authentication Flow:**
1. Authorization Code flow via browser callback
2. OAuth tokens include project\_id for quota API access
3. Token cached locally with auto-refresh
4. Proactive token refresh prevents mid-request failures
### Manual Authentication
```bash theme={null}
# Authenticate without starting a session
ccs agy --auth
# Headless mode (server/SSH environments)
ccs agy --headless
# → Displays URL for manual browser authentication
# → Includes SSH tunnel instructions if needed
```
### Logout
```bash theme={null}
# Clear all Antigravity tokens
ccs agy --logout
```
## Real-Time Quota Display
**Unique Feature:** CCS displays real-time quota percentages for Antigravity accounts.
```bash theme={null}
# Quota checked automatically before execution
ccs agy "your prompt"
# Output before Claude starts:
# [i] Antigravity Quota:
# Claude Opus 4.5 Thinking: 85% used (resets 2024-01-05 23:59:59 UTC)
# Gemini 3 Pro: 42% used (resets 2024-01-05 23:59:59 UTC)
```
**Quota API Integration:**
* Fetches from Antigravity internal API
* Displays usage percentage (0-100%)
* Shows reset time for each model
* Auto-refreshes tokens if expired
**Error Handling:**
* **403 Forbidden:** Account lacks quota access (displays warning)
* **Unprovisioned:** Account not activated in Antigravity app (prompts to sign in)
* **Token Expired:** Auto-refreshes via Google OAuth
## Multi-Account Support
Manage multiple Antigravity accounts for quota rotation:
### Add Account
```bash theme={null}
# Add new account (preserves existing)
ccs agy --auth --add
```
### List Accounts
```bash theme={null}
# Show all authenticated Antigravity accounts
ccs agy --accounts
# Output:
# Accounts for agy:
# [default] work (work@company.com) - Quota: 85%
# personal (personal@gmail.com) - Quota: 12%
```
### Switch Account
```bash theme={null}
# Switch to specific account by nickname
ccs agy --use personal
# Next command uses personal's account
ccs agy "your prompt"
```
### Rename Account
```bash theme={null}
# Rename default account nickname
ccs agy --nickname main-account
```
**Account Registry:** `~/.ccs/cliproxy/accounts.json`
**Auto-Nicknames:** Generated from email prefix (e.g., `john@gmail.com` → `john`)
## Model Configuration
Antigravity supports interactive model selection with extended context support:
```bash theme={null}
# Open model picker
ccs agy --config
# Interactive menu appears:
# Available models for Antigravity:
# 1. Claude Opus 4.6 Thinking (Recommended, default)
# 2. Claude Opus 4.6
# 3. Claude Sonnet 4.6 Thinking
# 4. Claude Sonnet 4.6
# 5. Gemini 3 Pro
# 6. Gemini 3 Pro Preview
# Select model [1-6]:
```
**Model Settings:** `~/.ccs/agy.settings.json`
**First-Run Behavior:** Prompts for model selection before first execution
**Extended Context Support:**
* Claude Opus 4.6: Use `--1m` flag for 1M token window (opt-in)
* Gemini 3 Pro: 1M token window auto-enabled by default
* Other models: Standard context windows
**Auto-Rotation:** CLIProxyAPI can auto-rotate accounts on rate limit (configured in `config.yaml`)
## Commands
### Basic Usage
```bash theme={null}
# Run with Antigravity
ccs agy "explain this architecture"
# Interactive chat
ccs agy
```
### Authentication Flags
| Flag | Description |
| -------------- | ------------------------------- |
| `--auth` | Trigger OAuth flow (no session) |
| `--logout` | Clear all tokens |
| `--headless` | Display URL for remote auth |
| `--auth --add` | Add new account (keep existing) |
### Account Management Flags
| Flag | Description |
| ------------------- | --------------------------------- |
| `--accounts` | List all accounts with quota info |
| `--use ` | Switch default account |
| `--nickname ` | Rename default account |
### Configuration Flags
| Flag | Description |
| ---------- | ------------------------ |
| `--config` | Interactive model picker |
## Storage Locations
| Path | Purpose |
| ----------------------------------------- | ------------------------------- |
| `~/.ccs/cliproxy/auth/antigravity-*.json` | OAuth tokens (one per account) |
| `~/.ccs/cliproxy/accounts.json` | Account registry with nicknames |
| `~/.ccs/agy.settings.json` | Model configuration |
| `~/.ccs/cliproxy/config.yaml` | CLIProxy unified config |
## Quota Management
### Pre-flight Check
CCS checks account quota before starting sessions:
```bash theme={null}
# Automatic quota check before execution
ccs agy "your prompt"
# → Checks all accounts, selects healthiest one
# → Skips exhausted or paused accounts
```
**Configuration:**
```yaml theme={null}
# config.yaml
quota_management:
mode: hybrid # auto | manual | hybrid
auto:
preflight_check: true # Check before request
exhaustion_threshold: 5 # Skip accounts below 5%
tier_priority: ["paid"] # Prefer paid accounts
cooldown_minutes: 5 # Skip exhausted for 5min
```
### Pause/Resume Accounts
Manually control which accounts are used:
```bash theme={null}
# Pause an account from rotation
ccs cliproxy pause agy user@gmail.com
# Resume a paused account
ccs cliproxy resume agy user@gmail.com
# Check status of all accounts
ccs cliproxy status agy
```
**Dashboard:** Pause/resume toggles also available in web dashboard account dropdown.
### Project ID Display
Dashboard shows GCP project\_id for each Antigravity account:
* **Location:** OAuth Providers → Antigravity → Account dropdown
* **Field:** Read-only with folder icon (`FolderCode`)
* **Privacy:** Respects privacy blur mode (Settings → Privacy)
* **Tooltip:** "GCP Project ID (read-only)"
**Warning State:** If project\_id shows "N/A" with warning badge:
* **Cause:** Account authenticated before project\_id tracking
* **Impact:** Quota API calls may fail
* **Solution:** Re-authenticate to refresh token with project\_id
```bash theme={null}
# Fix missing project_id
ccs agy --logout
ccs agy --auth
# Verify in Dashboard: OAuth Providers → Antigravity
```
### Account Tiers
Antigravity accounts have tier classifications for quota prioritization:
**Tier Types:**
| Tier | Description | Priority |
| --------- | -------------------------------------- | -------- |
| `ultra` | Premium tier with highest limits | Highest |
| `pro` | Professional tier with standard limits | Medium |
| `free` | Free tier with limited quota | Lowest |
| `unknown` | Tier detection failed | Lowest |
**Tier Storage:** `~/.ccs/cliproxy/accounts.json` → `.providers.agy.accounts[].tier`
**Tier Prioritization:**
CCS uses tier information for intelligent account selection:
```yaml theme={null}
# config.yaml
quota_management:
auto:
tier_priority: ["ultra", "pro", "free"] # Selection order
```
When multiple accounts are available, CCS prefers higher-tier accounts:
1. Select accounts with quota above threshold
2. Sort by tier (ultra, pro, free — highest first)
3. Use highest-tier account with available quota
**Dashboard Display:**
Tier badges appear in:
* Account list (`ccs agy --accounts`)
* Dashboard OAuth Providers → Antigravity dropdown
* Quota status cards
**Tier Detection:**
CCS reads the live Antigravity tier from `loadCodeAssist` whenever quota refresh runs. Manual tier values in `accounts.json` or the Dashboard remain useful as a fallback when the provider cannot return tier evidence.
### Token Format
```json theme={null}
{
"type": "antigravity",
"access_token": "...",
"refresh_token": "...",
"email": "user@example.com",
"expired": "2024-12-31T23:59:59Z",
"project_id": "..."
}
```
**Project ID:** Required for quota API calls, obtained during OAuth flow
### Quota API Endpoints
CCS uses Antigravity's internal API:
1. **loadCodeAssist** - Get project ID and tier evidence. CCS tries the daily Cloud Code host first and falls back to the production host if needed.
2. **fetchAvailableModels** - Get quota percentages & reset times
**Authentication:** OAuth tokens from `~/.ccs/cliproxy/auth/antigravity-*.json`
**Auto-Refresh:** Tokens refresh automatically if expired or expiring soon (under 5 minutes)
### Quota Response
```typescript theme={null}
{
models: [
{
name: "gemini-3-pro-high",
displayName: "Gemini 3 Pro",
percentage: 85, // 0-100
resetTime: "2024-01-05T23:59:59Z"
}
],
lastUpdated: 1704499200000,
isForbidden: false,
isUnprovisioned: false
}
```
## Requirements
* Antigravity subscription
* Browser for OAuth (or `--headless` for servers)
* Network access to Antigravity authentication servers
## Troubleshooting
### Quota Not Displaying
```bash theme={null}
# Check account status
ccs agy --accounts
# Re-authenticate if needed
ccs agy --logout
ccs agy --auth
```
### Account Unprovisioned
**Error:** "Account not activated in Antigravity app"
**Solution:** Sign in to Antigravity web app at least once to provision your account
### 403 Forbidden on Quota API
**Error:** "Account lacks quota access"
**Solution:** Verify subscription is active. Contact Antigravity support if issue persists.
### Project ID Shows N/A
**Warning:** "Project ID: N/A" in Dashboard account dropdown
**Cause:** OAuth token missing project\_id (authenticated before feature added)
**Solution:**
1. Remove account: `ccs agy --logout`
2. Re-authenticate: `ccs agy --auth`
3. Verify in Dashboard: OAuth Providers → Antigravity → Account dropdown
4. Confirm project\_id displays (e.g., "project-123456")
**Note:** Re-authentication is required only once per account. Project ID persists after successful OAuth.
### Token Expiry
Tokens refresh automatically. If refresh fails:
```bash theme={null}
# Re-authenticate
ccs agy --auth
```
## Cost Information
**Antigravity Subscription Required:** Check antigravity.dev for current pricing
**Usage Limits:** Subject to quota limits shown in real-time display
## Next Steps
Manage multiple Antigravity accounts
# Claude Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/claude
Anthropic Claude OAuth provider with automatic token refresh and multi-account support
# Claude Provider
Access Anthropic Claude models via OAuth authentication with automatic token management and seamless multi-account support.
## Quick Start
```bash theme={null}
# Create named account and authenticate
ccs auth create work
# Use account by name
ccs work "explain this code"
# Or use the generic claude provider
ccs claude "explain this code"
# List all accounts
ccs claude --accounts
```
## Authentication
### Initial Setup
Run `ccs claude "your prompt"` - browser opens automatically
Sign in with your Claude account (requires Claude Pro/Max subscription)
OAuth token saved to `~/.ccs/cliproxy/auth/claude-{email}.json`
Token refreshes automatically 5 minutes before expiry
### OAuth Flow Specifics
**Authorization Code Flow:**
* Callback server spawns on port 54545
* Browser opens for Claude OAuth consent
* Token received via HTTP callback
* Auto-refresh prevents mid-request failures
**Proactive Token Refresh:**
* Checks `expiry_date` before each execution
* Refreshes 5 minutes before expiry (matches CLIProxyAPI)
* Prevents `UND_ERR_SOCKET` errors during long sessions
* Graceful re-auth prompt if refresh fails
### Headless Authentication
For servers without browser access:
```bash theme={null}
ccs claude --headless
# Output:
# Open this URL on any device:
# https://claude.ai/oauth/authorize?...
#
# Waiting for authentication...
```
Complete OAuth on another device - CCS detects when token is cached.
## Multi-Account Support
Manage multiple Claude accounts seamlessly:
```bash theme={null}
# Add second account (preserves existing)
ccs claude --auth --add
# Auto-nicknamed from email prefix
# john@gmail.com → "john"
```
```bash theme={null}
ccs claude --accounts
# Output:
# Available Claude accounts:
# * john (john@gmail.com) - default
# work (alice@company.com)
```
```bash theme={null}
# Switch default account
ccs claude --use work
# Rename account
ccs claude --nickname personal
```
**Account Registry:** `~/.ccs/cliproxy/accounts.json`
```json theme={null}
{
"version": 1,
"providers": {
"claude": {
"default": "john@gmail.com",
"accounts": {
"john@gmail.com": {
"email": "john@gmail.com",
"nickname": "john",
"tokenFile": "claude-john@gmail.com.json",
"createdAt": "2024-01-01T00:00:00Z",
"lastUsedAt": "2024-01-05T12:00:00Z"
}
}
}
}
}
```
## Commands Reference
### Basic Usage
```bash theme={null}
# Execute with default model
ccs claude "your prompt"
# One-shot mode (exit after response)
ccs claude "explain this function"
```
### Authentication Commands
```bash theme={null}
# Trigger OAuth (no session)
ccs claude --auth
# Add new account (preserves existing)
ccs claude --auth --add
# Logout (clear tokens)
ccs claude --logout
# Headless mode (no browser)
ccs claude --headless
```
### Account Management
```bash theme={null}
# List all accounts
ccs claude --accounts
# Switch default account
ccs claude --use work
# Rename current account
ccs claude --nickname personal
```
## Configuration
### Config Keys
Configure via `~/.ccs/config.yaml`:
```yaml theme={null}
# CLIProxy settings
cliproxy:
auth:
api_key: "ccs-internal-managed"
management_secret: "ccs" # Dashboard login password
```
### Environment Variables
These are set automatically by CCS. Manual override rarely needed.
```bash theme={null}
# Claude CLI injection (auto-managed)
ANTHROPIC_BASE_URL=http://127.0.0.1:8317
ANTHROPIC_AUTH_TOKEN=ccs-internal-managed
```
## Storage Locations
| Path | Description |
| ------------------------------------ | ------------------------------ |
| `~/.ccs/cliproxy/auth/claude-*.json` | OAuth tokens (one per account) |
| `~/.ccs/cliproxy/accounts.json` | Account registry, nicknames |
| `~/.ccs/cliproxy/config.yaml` | CLIProxy configuration |
## Requirements
* Claude Pro or Claude Max subscription
* Browser for OAuth (or `--headless` for servers)
* Network access to Claude authentication servers
## Token Management
**Storage Format:**
```json theme={null}
{
"type": "claude",
"access_token": "sk-ant-...",
"refresh_token": "...",
"email": "user@example.com",
"expired": "2024-12-31T23:59:59Z",
"expiry_date": 1735689599000
}
```
**Auto-Refresh:** Tokens refresh automatically 5 minutes before expiry
**Security:** Tokens stored locally, never transmitted except to Anthropic
## Troubleshooting
### Token Refresh Failures
**Symptom:** `UND_ERR_SOCKET` errors during execution
**Cause:** Token expired mid-request
**Solution:** Proactive refresh handles this automatically. If issue persists:
```bash theme={null}
# Clear and re-authenticate
ccs claude --logout
ccs claude --auth
```
### Browser Doesn't Open
**Symptom:** OAuth flow stuck waiting for browser
**Solution:** Use headless mode:
```bash theme={null}
ccs claude --headless
# Copy URL to browser manually
```
### Multiple Accounts Confusion
**Symptom:** Wrong account being used
**Solution:** Check default account:
```bash theme={null}
# View all accounts (default marked with *)
ccs claude --accounts
# Switch default
ccs claude --use work
```
## Quota Windows
Claude OAuth uses rolling quota windows that CCS tracks for automatic account rotation:
| Window | Duration | Notes |
| ------ | -------- | ------------------------- |
| Short | 5 hours | Primary rate limit window |
| Weekly | 7 days | Secondary quota window |
**Failover behavior:** When a Claude OAuth account hits its quota, CCS automatically fails over to the next available account in the rotation (if multiple accounts configured). View quota status with:
```bash theme={null}
ccs cliproxy quota # All providers including claude
ccs cliproxy status claude # Claude-specific status
```
To turn several Claude accounts into a pool that auto-continues a single
conversation across the limit (fill-first plus session affinity), see
[Account Pools](/features/pool). That page covers the three-command setup,
the slower turn right after a failover hop, leaving a pool, and migrating from
native profiles.
## Cost Information
| Tier | Models | Cost |
| ---------- | ---------------------------------------------------------- | ----------- |
| Claude Pro | Claude Opus 4.6, Opus 4.5, Sonnet 4.5, Sonnet 4, Haiku 4.5 | \$20/month |
| Claude Max | All Pro models (extended usage) | \$200/month |
Claude provider requires an active Claude Pro or Max subscription. Free tier accounts are not supported.
## Advanced Features
### Isolated Instances
Each named account (`ccs auth create `) gets its own directory:
```
~/.ccs/instances//
├── .credentials.json # OAuth credentials
├── session-env/ # Chat history
└── commands/ # Custom commands
```
This enables running two accounts simultaneously without session conflicts.
### Shared Context Groups
Opt in to sharing context across accounts:
```yaml theme={null}
# ~/.ccs/config.yaml
accounts:
work:
context_group: "team-alpha"
work-backup:
context_group: "team-alpha"
```
See [Claude Accounts](/providers/concepts/claude-accounts) for full details.
### Deeper Continuity
```bash theme={null}
# Maintain memory across sessions
ccs work --deeper-continuity "continue the refactor"
```
## Next Steps
Full guide to multiple Claude account management
Compare all available providers
Connect to external CLIProxy server
Config file reference
# CodeBuddy Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/codebuddy
Use Tencent CodeBuddy through CCS as a CLIProxy OAuth provider
# CodeBuddy Provider
CCS supports **CodeBuddy (Tencent)** as a CLIProxy OAuth provider.
## Quick Start
```bash theme={null}
ccs codebuddy --auth
ccs codebuddy --accounts
ccs codebuddy --config
ccs codebuddy "inspect this implementation"
```
## Authentication Model
CodeBuddy currently uses a **browser-driven polling flow** through
CLIProxyAPIPlus:
* no local callback port is required
* CCS waits for upstream auth completion
* token refresh is delegated to CLIProxy
## Backend Requirement
CodeBuddy is a **plus-only** provider.
```yaml theme={null}
cliproxy:
backend: plus
```
## Config And Storage
| Path | Purpose |
| -------------------------------- | ---------------------------------------------------- |
| `~/.ccs/cliproxy/auth/` | shared OAuth token directory |
| `~/.ccs/codebuddy.settings.json` | provider settings when a local settings file is used |
## Current Scope
CCS documents CodeBuddy today as an auth and routing provider surface. As with
Cursor, it does not currently participate in the local static model-catalog
sync path used by the older catalog-backed provider set.
## Related
* [Provider Overview](/providers/concepts/overview)
* [CLIProxy API](/features/proxy/cliproxy-api)
# Codex Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/codex
Access OpenAI Codex models via OAuth authentication
# Codex Provider
Access OpenAI Codex models through browser-based OAuth authentication. CCS defaults to the current Codex-recommended models and repairs known paid-only or preview-only defaults when the active account cannot use them.
## Overview
The Codex provider enables Claude Code to use OpenAI's Codex models through OAuth authentication - no API keys required. Simply authenticate once and CCS handles token management automatically.
**Provider Identifier:** `codex`
**Command:** `ccs codex`
**Supported Models:**
* GPT-5.6 Sol - latest frontier agentic coding model
* GPT-5.6 Terra - balanced agentic coding model for everyday work
* GPT-5.6 Luna - fast, affordable agentic coding model
* GPT-5.4 - recommended default for most Codex tasks
* GPT-5.4 Mini - fast, lower-cost option for lighter tasks and subagents
* GPT-5.2 and GPT-5.3 Codex as older alternatives
* GPT-5.3 Codex Spark in research preview for ChatGPT Pro subscribers
* Interactive model picker via `--config`
## Plan-Aware Defaults
Available since v7.54.0
CCS now checks the active Codex quota plan before startup when your settings reference a known paid-only or preview-only model.
* If the active account is on the free Codex plan, CCS keeps your saved settings but sends runtime requests through `gpt-5.4`
or `gpt-5.4-mini` when the configured model is restricted
* If CCS cannot verify the plan, it keeps your current model and prints a targeted warning with the safe fallback
* The runtime fallback only touches known restricted Codex defaults (`gpt-5.5`, `gpt-5.3-codex`, and `gpt-5.3-codex-spark`); it does not rewrite unrelated provider settings
## Authentication
### First-Time Setup
```bash theme={null}
# Run Codex for the first time
ccs codex "explain this code"
# Browser opens automatically
# → Complete OAuth login
# → Token cached at ~/.ccs/cliproxy/auth/
# → Future runs require no re-auth
```
**Authentication Flow:**
1. Authorization Code flow via browser callback
2. Callback server spawns on provider-specific port
3. Token cached locally with auto-refresh
4. Proactive token refresh prevents mid-request failures
### Manual Authentication
```bash theme={null}
# Authenticate without starting a session
ccs codex --auth
# Headless mode (server/SSH environments)
ccs codex --headless
# → Displays URL for manual browser authentication
# → Includes SSH tunnel instructions if needed
```
### Logout
```bash theme={null}
# Clear all Codex tokens
ccs codex --logout
```
## Multi-Account Support
Manage multiple OpenAI accounts for different projects:
### Add Account
```bash theme={null}
# Add new account (preserves existing)
ccs codex --auth --add
```
### List Accounts
```bash theme={null}
# Show all authenticated Codex accounts
ccs codex --accounts
# Output:
# Accounts for codex:
# [default] john (john@example.com)
# sarah (sarah@company.com)
```
### Switch Account
```bash theme={null}
# Switch to specific account by nickname
ccs codex --use sarah
# Next command uses sarah's account
ccs codex "your prompt"
```
### Reauthenticate Account
Use Dashboard → CLIProxy → Codex → account menu → Reauthenticate to refresh one
imported or existing account without creating a duplicate account record.
### Rename Account
```bash theme={null}
# Rename default account nickname
ccs codex --nickname work-account
```
**Account Registry:** `~/.ccs/cliproxy/accounts.json`
**Auto-Nicknames:** Generated from email prefix (e.g., `john@gmail.com` → `john`)
## Real-Time Quota Display
CCS displays real-time quota information for Codex accounts via Dashboard and CLI.
### Weekly Reset Schedule
Since v7.44.0, the dashboard exposes the weekly reset schedule for Codex
accounts, showing exactly when your weekly quota resets.
### Dashboard Display
**Location:** Dashboard → CLIProxy → Codex provider view
**Displays:**
* Core 5-hour usage window (e.g., "45/50 messages")
* Core weekly usage window (e.g., "210/500 messages")
* 5-hour limit reset time
* Weekly limit reset time (with schedule)
* Additional feature windows such as Codex Spark in tooltip/detail views when
the upstream exposes them
**Backend Caching:**
* Quota data cached for 2 minutes to reduce API load
* Automatic re-authentication if token expired
* Dashboard shows cached timestamp
### CLI Quota Check
```bash theme={null}
# View quota for all Codex accounts
ccs cliproxy quota --provider codex
# Output:
# Codex Quota (as of 2026-02-04 18:00:00):
# john@example.com:
# 5-hour: 45/50 messages (resets in 6h)
# Weekly: 210/500 messages (resets in 2d 6h)
```
**Features:**
* Displays all authenticated Codex accounts
* Shows cached timestamp (2-minute cache)
* Indicates if re-authentication needed
* Keeps preview or feature-specific windows separate from the core 5-hour and
weekly summary so extra limits do not replace the main account view
**Quota Response Caching:**
CCS caches quota responses to prevent excessive API calls:
| Cache Duration | Applies To |
| -------------- | -------------------------------------- |
| 2 minutes | Quota data (usage counts, reset times) |
| Token refresh | Automatic if expired during fetch |
**Cache Location:** In-memory (not persisted to disk)
## Model Information
**Available Models:**
| Model ID | Name | Max Effort | Fast Tier | Notes |
| --------------------- | ------------------- | ---------- | --------- | ----------------------------- |
| `gpt-5.6-sol` | GPT-5.6 Sol | `xhigh` | Yes | Frontier agentic coding model |
| `gpt-5.6-terra` | GPT-5.6 Terra | `xhigh` | Yes | Balanced everyday model |
| `gpt-5.6-luna` | GPT-5.6 Luna | `xhigh` | Yes | Fast, affordable model |
| `gpt-5.5` | GPT-5.5 | `xhigh` | Yes | Newest paid Codex model |
| `gpt-5.4` | GPT-5.4 | `xhigh` | Yes | Recommended Codex default |
| `gpt-5.4-mini` | GPT-5.4 Mini | `high` | No | Default fast / haiku option |
| `gpt-5.2` | GPT-5.2 | `xhigh` | No | Older general-purpose model |
| `gpt-5.3-codex` | GPT-5.3 Codex | `xhigh` | No | Older paid Codex model |
| `gpt-5.3-codex-spark` | GPT-5.3 Codex Spark | `xhigh` | No | Research preview, ChatGPT Pro |
### Catalog Context Windows
In the current development CLI source, programmatic catalog output includes
`contextWindow` when CCS knows an authoritative token limit:
```bash theme={null}
ccs cliproxy catalog --json
```
For Claude-target CLIProxy launches, CCS uses the effective provider and model
catalog entry to set `CLAUDE_CODE_AUTO_COMPACT_WINDOW` automatically. An exact
uppercase environment key already present wins by presence, including an empty
value. Unknown or custom models remain unchanged because CCS does not guess a
window.
This automatic environment injection is specific to Claude-target launch
construction; it does not describe behavior for non-Claude targets.
**Model Suffixes:** Append effort level directly: `gpt-5.5-minimal`, `gpt-5.5-low`, `gpt-5.3-codex-medium`, `gpt-5.3-codex-high`, `gpt-5.3-codex-xhigh`.
GPT-5.6 Sol, Terra, and Luna support `low`, `medium`, `high`, and `xhigh` suffixes. CCS does not advertise `minimal`, `max`, or `ultra` for those models.
**Fast Service Tier:** Append `-fast` to supported GPT model IDs. Combine it
with an effort suffix when both should be pinned:
```bash theme={null}
gpt-5.4-fast
gpt-5.4-low-fast
gpt-5.4-high-fast
gpt-5.4-xhigh-fast
gpt-5.5-high-fast
```
CCS translates these aliases before sending the request upstream. For example,
`gpt-5.4-high-fast` becomes upstream model `gpt-5.4` with
`reasoning.effort: "high"` and `service_tier: "priority"`, which is the Codex
request value for fast mode.
The same pattern also works for a structured Codex fast alias in CCS config.
For example, a `cliproxy.oauth_model_alias.codex` entry like
`gpt-5.6-sol-fast` can map to upstream `gpt-5.6-sol`, while a matching
`cliproxy.payload.override` rule keeps `service_tier: priority` attached to that
alias through regeneration.
### Configure Fast Mode
Use a CLIProxy variant when you want Claude Code or compatible clients to use a
specific Codex GPT speed/effort combination:
```bash theme={null}
ccs cliproxy create codex-fast --provider codex --model gpt-5.4-high-fast
ccs codex-fast "review this change"
```
In the dashboard, open `ccs config`, go to `CLIProxy`, and create or edit a
Codex variant. Select a supported Codex model, then use the **Fast** switch
beside **Effort**. The switch adds or removes `-fast` without changing the
selected effort or a routing prefix. It also remains available for a custom
value that already ends in `-fast`. The raw environment form is also valid:
```json theme={null}
{
"env": {
"ANTHROPIC_MODEL": "gpt-5.4-high-fast",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5.4-xhigh-fast",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.4-high-fast",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5.4-medium-fast"
}
}
```
```yaml theme={null}
cliproxy:
oauth_model_alias:
codex:
- name: gpt-5.6-sol
alias: gpt-5.6-sol-fast
fork: true
payload:
override:
- models:
- name: gpt-5.6-sol-fast
protocol: codex
params:
service_tier: priority
```
## Reasoning Effort
CCS automatically injects OpenAI's `reasoning.effort` parameter. The configured slot requests a default effort, then CCS caps it to the selected model's supported maximum.
### Dashboard Effort And Fast Controls
In `ccs config`, each Codex tier in the CLIProxy model mapping includes an
**Effort** dropdown. **Auto** removes any explicit effort suffix; the other
choices match the selected model's supported effort levels. Changing effort
preserves an existing `-fast` service-tier suffix, such as changing
`gpt-5.4-high-fast` to `gpt-5.4-low-fast`. For supported models, the separate
**Fast** switch controls that suffix without changing the effort selection.
### Effort Levels
| Level | Description | Token Budget |
| --------- | ------------------ | ----------------- |
| `minimal` | Lightest reasoning | Lowest usage |
| `low` | Light reasoning | Low usage |
| `medium` | Standard reasoning | Base level |
| `high` | Deep reasoning | Moderate increase |
| `xhigh` | Maximum depth | Up to 32K tokens |
### Automatic Effort Mapping
| Source | Requested Effort | Effective Behavior |
| ------------------------- | ---------------- | -------------------------------------------------- |
| Default / Opus slot | `xhigh` | Capped by the selected model's max supported level |
| Sonnet slot | `high` | Used as-is unless the model only supports lower |
| Haiku slot | `medium` | Used as-is |
| `--effort` / model suffix | Explicit value | Used, then capped if the model cannot support it |
### How It Works
When you use Codex, CCS derives the effort from your configuration and then applies model-specific caps:
```bash theme={null}
# Default Codex model is gpt-5.4, so xhigh remains available
ccs codex "complex analysis task"
# Override effort explicitly
ccs codex --effort xhigh "deep analysis"
ccs codex --thinking xhigh "same as --effort (alias)"
# Model suffix pins effort
ccs codex # model: gpt-5.5-low -> effort: low
# Model suffix pins effort and fast service tier
ccs codex # model: gpt-5.4-high-fast -> effort: high, service_tier: priority
```
### Cost Implications
Higher reasoning effort increases token consumption:
* `xhigh`: Maximum tokens, deepest analysis
* `high`: Moderate token increase
* `medium`: Standard token usage
* `low` / `minimal`: Lower usage for lightweight tasks
Reasoning effort is injected transparently. You don't need to configure
anything unless you want to override it. Unsupported higher efforts are capped
to the model's max level automatically.
### Trace Logging
Enable verbose mode to see reasoning effort in request logs:
```bash theme={null}
ccs codex --verbose "your task"
# Output includes: reasoning.effort: xhigh
```
## Runtime Targets
Available since v7.62.0
CCS can route the Codex provider to different CLI runtimes:
### Native Codex Runtime
Use `ccs-codex`, `ccsx`, or `ccsxp` to run the Codex provider on the native Codex CLI:
```bash theme={null}
# Built-in aliases
ccs-codex "your prompt"
ccsx codex "implement auth flow"
# Codex-on-Codex power shortcut: native Codex + CLIProxy Codex pool
ccsxp "your prompt"
# Explicit target flag
ccs codex --target codex "your prompt"
```
Most Codex target launches use transient `-c` overrides and `CCS_CODEX_API_KEY` env injection. `ccsxp` is the managed exception: it repairs the native Codex `[model_providers.cliproxy]` entry if missing or incomplete, then injects the managed token into that provider's configured `env_key` for the spawned Codex process. No API key is written to `~/.codex/config.toml`.
`ccsxp` keeps Codex history in native `~/.codex` by default, even if the parent shell has another `CODEX_HOME` set. Use `CCSXP_CODEX_HOME` only when you intentionally want separate `ccsxp` history.
Pooling and round-robin behavior are controlled by CLIProxy routing, not by the Codex config file:
```bash theme={null}
ccs cliproxy routing
ccs cliproxy routing set round-robin
```
See [Codex Adapter](/features/workflow/codex-adapter) for full details on
supported profile types, alias configuration, and the dashboard control
center.
### Droid Runtime
Use Codex with the `ccs-droid` target for automated agent workflows:
```bash theme={null}
ccs-droid codex "run this task autonomously"
```
This routes the Codex provider through CCS's Droid runtime for non-interactive automated execution.
## Commands
### Basic Usage
```bash theme={null}
# Run with Codex
ccs codex "implement authentication flow"
# Interactive chat
ccs codex
# With reasoning effort
ccs codex --thinking xhigh "design this system"
```
### Authentication Flags
| Flag | Description |
| -------------- | ------------------------------- |
| `--auth` | Trigger OAuth flow (no session) |
| `--logout` | Clear all tokens |
| `--headless` | Display URL for remote auth |
| `--auth --add` | Add new account (keep existing) |
### Account Management Flags
| Flag | Description |
| ------------------- | ---------------------- |
| `--accounts` | List all accounts |
| `--use ` | Switch default account |
| `--nickname ` | Rename default account |
## Storage Locations
| Path | Purpose |
| ----------------------------------- | ------------------------------- |
| `~/.ccs/cliproxy/auth/codex-*.json` | OAuth tokens (one per account) |
| `~/.ccs/cliproxy/accounts.json` | Account registry with nicknames |
| `~/.ccs/codex.settings.json` | Model configuration |
| `~/.ccs/cliproxy/config.yaml` | CLIProxy unified config |
## Requirements
* OpenAI account with Codex OAuth access
* Browser for OAuth (or `--headless` for servers)
* Network access to OpenAI authentication servers
## Token Management
**Storage Format:**
```json theme={null}
{
"type": "codex",
"access_token": "...",
"refresh_token": "...",
"email": "user@example.com",
"expired": "2024-12-31T23:59:59Z"
}
```
**Auto-Refresh:** Tokens refresh automatically 5 minutes before expiry
**Security:** Tokens stored locally, never transmitted except to OpenAI
## Troubleshooting
### Browser Won't Open
```bash theme={null}
# Use headless mode
ccs codex --headless
# Complete auth on another device
# CCS detects when token is cached
```
### Multi-Account Issues
```bash theme={null}
# List all accounts to verify state
ccs codex --accounts
# Clear and re-authenticate
ccs codex --logout
ccs codex --auth
```
### Token Expiry
Tokens refresh automatically. If refresh fails:
```bash theme={null}
# Re-authenticate
ccs codex --auth
```
## Cost Information
**Plan Access:** Use `gpt-5.4` for the default Codex path and `gpt-5.4-mini` for the fast path. `gpt-5.5` and older models such as `gpt-5.3-codex` require paid Codex access, while `gpt-5.3-codex-spark` is a research preview model for ChatGPT Pro subscribers.
**Usage Limits:** Subject to OpenAI's rate limits and fair use policy
## Next Steps
Manage multiple Codex accounts
Configure via web interface
# Cursor Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/cursor
Authenticate Cursor through the current CLIProxy provider path in CCS
# Cursor Provider
CCS now treats **Cursor** as a first-class CLIProxy OAuth provider. Use this
page for the current `ccs cursor` auth and account-management flow.
The older local Cursor daemon bridge is still available only as deprecated
compatibility under [`ccs legacy cursor`](/features/workflow/cursor). Do not use
the old `ccs cursor auth/status/start/...` examples from earlier docs for new
setups.
## Quick Start
```bash theme={null}
# Authenticate the current provider path
ccs cursor --auth
# Inspect accounts
ccs cursor --accounts
# Open provider config flow
ccs cursor --config
# Run a task through Cursor's CLIProxy route
ccs cursor "review this diff"
```
## Authentication Model
Cursor uses a **browser-driven polling flow** through CLIProxyAPIPlus:
* no local callback port is required
* CCS opens the upstream Cursor login page and polls for completion
* token refresh is delegated to CLIProxy
## Backend Requirement
Cursor is a **plus-only** provider.
```yaml theme={null}
cliproxy:
backend: plus
```
If you force `--backend original`, Cursor auth will not be available.
## Config And Storage
Cursor is the only CLIProxy provider that stores its provider settings in a
dedicated namespace so it does not collide with the deprecated local bridge
files:
| Path | Purpose |
| ------------------------------------------------ | ------------------------------------------- |
| `~/.ccs/cliproxy/auth/` | shared OAuth token directory |
| `~/.ccs/cliproxy/providers/cursor.settings.json` | current Cursor provider settings |
| `~/.ccs/cursor.settings.json` | deprecated local Cursor IDE bridge settings |
## Commands You Will Actually Use
```bash theme={null}
ccs cursor --auth
ccs cursor --accounts
ccs cursor --use
ccs cursor --nickname
ccs cursor --config
ccs cursor --logout
```
## Current Scope
CCS documents Cursor here as a **provider-auth and routing surface**. The
provider is current and supported, but it does **not** currently participate in
the same local static model-catalog sync flow used by `agy`, `claude`,
`codex`, `gemini`, `ghcp`, `iflow`, `kimi`, and `kiro`.
Use the legacy bridge page only if you still need the reverse-engineered local
Cursor daemon compatibility path.
## Related
* [Provider Overview](/providers/concepts/overview)
* [CLIProxy API](/features/proxy/cliproxy-api)
* [Cursor IDE Bridge (Legacy)](/features/workflow/cursor)
# Gemini Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/gemini
Google Gemini OAuth provider with automatic CLIProxy-managed refresh and model selection
# Gemini Provider
Access Google Gemini models via OAuth authentication with automatic token management and interactive model configuration.
## Quick Start
```bash theme={null}
# First run (browser opens for OAuth)
ccs gemini "explain this code"
# Select model interactively
ccs gemini --config
# Use specific account
ccs gemini --use work
```
## Authentication
### Initial Setup
Run `ccs gemini "your prompt"` - browser opens automatically
Sign in with your Google account
OAuth token saved to `~/.ccs/cliproxy/auth/gemini-{email}.json`
Token refresh is handled automatically by CLIProxy
### OAuth Flow Specifics
**Authorization Code Flow:**
* Callback server spawns on provider-specific port
* Browser opens for Google OAuth consent
* Token received via HTTP callback
* Runtime-managed refresh prevents mid-request failures
**Automatic Token Refresh:**
* refresh ownership is delegated upstream to CLIProxy
* CCS verifies that local auth material still exists
* prevents common mid-session auth failures without requiring manual refresh in normal flows
* prompts for re-auth if upstream refresh can no longer recover the session
### Headless Authentication
For servers without browser access:
```bash theme={null}
ccs gemini --headless
# Output:
# Open this URL on any device:
# https://accounts.google.com/o/oauth2/auth?...
#
# Waiting for authentication...
```
Complete OAuth on another device - CCS detects when token is cached.
## Multi-Account Support
Manage multiple Google accounts seamlessly:
```bash theme={null}
# Add second account (preserves existing)
ccs gemini --auth --add
# Auto-nicknamed from email prefix
# john@gmail.com → "john"
```
```bash theme={null}
ccs gemini --accounts
# Output:
# Available Gemini accounts:
# * john (john@gmail.com) - default
# work (alice@company.com)
```
```bash theme={null}
# Switch default account
ccs gemini --use work
# Rename account
ccs gemini --nickname personal
```
**Account Registry:** `~/.ccs/cliproxy/accounts.json`
## Real-Time Quota Display
CCS displays real-time quota information for Gemini accounts via Dashboard and CLI.
### Dashboard Display
**Location:** Dashboard → OAuth Providers → Gemini
**Displays:**
* Requests per minute (RPM) usage
* Tokens per minute (TPM) usage
* Requests per day (RPD) usage
* Limit reset times
**Backend Caching:**
* Quota data cached for 2 minutes to reduce API load
* Automatic re-authentication if token expired
* Dashboard shows cached timestamp
### CLI Quota Check
```bash theme={null}
# View quota for all Gemini accounts
ccs cliproxy quota --provider gemini
# Output:
# Gemini Quota (as of 2026-02-04 18:00:00):
# john@gmail.com:
# RPM: 45/60 requests (resets in 30s)
# TPM: 28000/32000 tokens (resets in 30s)
# RPD: 890/1500 requests (resets in 6h)
```
**Features:**
* Displays all authenticated Gemini accounts
* Shows cached timestamp (2-minute cache)
* Proactive token refresh (5 minutes before expiry)
**Quota Response Caching:**
CCS caches quota responses to prevent excessive API calls:
| Cache Duration | Applies To |
| -------------- | --------------------------------------------------- |
| 2 minutes | Quota data (usage counts, reset times) |
| Token refresh | Proactive (5min before expiry, matches CLIProxyAPI) |
**Cache Location:** In-memory (not persisted to disk)
## Tool Name Sanitization
Gemini enforces a 64-character limit on tool names. CCS automatically handles this via ToolSanitizationProxy.
### The Problem
Claude MCP tools can have names exceeding 64 characters:
```
mcp__filesystem__read_multiple_files # 37 chars - OK
mcp__sequential-thinking__recordThoughtSequence # 50 chars - OK
mcp__very-long-server-name__someVeryLongToolNameHere # 70+ chars - FAILS
```
**Gemini API Error:** "Invalid tool name: must be 64 characters or fewer"
### How CCS Fixes It
**ToolSanitizationProxy** intercepts requests and:
1. Detects tool names exceeding 64 characters
2. Creates short hashes using `_<6-char-md5>` format (e.g., `mcp__long-server__toolName` → `mcp___a1b2c3`)
3. Maintains bidirectional mapping
4. Restores original names in responses
### Architecture
```
Claude CLI → ToolSanitizationProxy → CLIProxy → Gemini API
↓ Sanitize request ↓ Forward ↓ Process
↑ Restore response ↑ Return ↑ Respond
```
**Proxy Lifecycle:**
* Spawned automatically when using Gemini provider
* Runs on random port (127.0.0.1)
* Shuts down with Claude session
### Sanitization Process
**Request Flow:**
```json theme={null}
// Original (Claude CLI sends)
{
"tools": [
{ "name": "mcp__very-long-server__someVeryLongToolNameThatExceeds64Chars" }
]
}
// Sanitized (Proxy → Gemini)
{
"tools": [
{ "name": "mcp___a1b2c3" }
]
}
```
**Response Flow:**
```json theme={null}
// Gemini response
{
"content": [
{ "type": "tool_use", "name": "mcp___a1b2c3" }
]
}
// Restored (Proxy → Claude CLI)
{
"content": [
{ "type": "tool_use", "name": "mcp__very-long-server__someVeryLongToolNameThatExceeds64Chars" }
]
}
```
### Debug Mode
Enable verbose logging to see sanitization activity:
```bash theme={null}
export CCS_DEBUG=1
ccs gemini "use long tool names"
# Logs appear in: ~/.ccs/logs/tool-sanitization-proxy.log
# Console output (if CCS_DEBUG=1):
# [i] ToolSanitizationProxy started on port 54321
# [!] Sanitized 2 tool names (64-char limit)
# [i] Restored 1 tool name in response
```
**Log Location:** `~/.ccs/logs/tool-sanitization-proxy.log`
### When Sanitization Happens
**Automatically enabled for:**
* All CLIProxy providers (gemini, codex, antigravity)
* Any provider configured via `config.cliproxy`
**Why all providers?**
* ToolSanitizationProxy runs for all CLIProxy-based providers to ensure compatibility across different model APIs
### Configuration
Sanitization is automatic and requires no configuration. To disable warnings:
```yaml theme={null}
# config.yaml (not yet implemented - always warns)
cliproxy:
tool_sanitization:
warn_on_sanitize: false
```
### Performance Impact
**Minimal overhead:**
* Hash generation: under 1ms per tool
* Request/response transformation: under 5ms
* In-memory mapping (no disk I/O)
**Timeout:** 120 seconds (configurable via `timeoutMs`)
```json theme={null}
{
"version": 1,
"providers": {
"gemini": {
"default": "john@gmail.com",
"accounts": {
"john@gmail.com": {
"email": "john@gmail.com",
"nickname": "john",
"tokenFile": "gemini-john@gmail.com.json",
"createdAt": "2024-01-01T00:00:00Z",
"lastUsedAt": "2024-01-05T12:00:00Z"
}
}
}
}
}
```
## Model Configuration
### Interactive Model Picker
Select Gemini model interactively with `--config` flag:
```bash theme={null}
ccs gemini --config
# Interactive prompt:
# Available models for Gemini:
# 1. Gemini 3 Pro - Recommended (latest model, paid account required)
# 2. Gemini 2.5 Pro - Free tier (works with free Google account)
# Select model [1-2]: 1
```
**First-Run Detection:** If no model configured, prompts automatically before first execution.
### Available Models
| Model ID | Name | Tier | Notes |
| ---------------------- | -------------- | ---- | ------------------------------------------ |
| `gemini-3-pro-preview` | Gemini 3 Pro | Pro | Latest model, requires paid Google account |
| `gemini-2.5-pro` | Gemini 2.5 Pro | Free | Stable, works with free Google account |
Gemini 3 Pro requires a paid Google account. Use Gemini 2.5 Pro for free tier.
### Model Settings Storage
Settings saved to `~/.ccs/gemini.settings.json`:
```json theme={null}
{
"model": "gemini-3-pro-high",
"maxTokens": 8192
}
```
**Priority:** Custom settings → User overrides → Bundled defaults
## Configuration
### Config Keys
Configure via `~/.ccs/config.yaml`:
```yaml theme={null}
# WebSearch integration
websearch:
providers:
gemini:
model: "gemini-2.5-pro" # Model for WebSearch hook
timeout: 30000 # CLI timeout (ms)
# CLIProxy settings
cliproxy:
auth:
api_key: "ccs-internal-managed"
management_secret: "ccs" # Dashboard login password
```
### Environment Variables
These are set automatically by CCS. Manual override rarely needed.
```bash theme={null}
# Claude CLI injection (auto-managed)
ANTHROPIC_BASE_URL=http://127.0.0.1:8317/api/provider/gemini
ANTHROPIC_AUTH_TOKEN=ccs-internal-managed
ANTHROPIC_MODEL=gemini-3-pro-high
ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-3-pro-high
ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-3-flash
ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-3-flash
ANTHROPIC_MAX_TOKENS=8192
```
## Commands Reference
### Basic Usage
```bash theme={null}
# Execute with default model
ccs gemini "your prompt"
# One-shot mode (exit after response)
ccs gemini "explain this function"
```
### Authentication Commands
```bash theme={null}
# Trigger OAuth (no session)
ccs gemini --auth
# Add new account (preserves existing)
ccs gemini --auth --add
# Logout (clear tokens)
ccs gemini --logout
# Headless mode (no browser)
ccs gemini --headless
```
### Account Management
```bash theme={null}
# List all accounts
ccs gemini --accounts
# Switch default account
ccs gemini --use work
# Rename current account
ccs gemini --nickname personal
```
### Configuration
```bash theme={null}
# Interactive model picker
ccs gemini --config
# Dashboard configuration
ccs config
```
## Troubleshooting
### Token Refresh Failures
**Symptom:** `UND_ERR_SOCKET` errors during execution
**Cause:** Token expired mid-request
**Solution:** Proactive refresh handles this automatically. If issue persists:
```bash theme={null}
# Clear and re-authenticate
ccs gemini --logout
ccs gemini --auth
```
### Model Not Working
**Symptom:** API errors, tool call failures
**Cause:** Model incompatible with Claude Code
**Solution:** Change model via `--config`:
```bash theme={null}
ccs gemini --config
# Select "Gemini 3 Pro (High)" - most reliable
```
Gemini 3 Pro (Preview) has known issues with tool calls. Use "High" variant instead.
### Multiple Accounts Confusion
**Symptom:** Wrong account being used
**Solution:** Check default account:
```bash theme={null}
# View all accounts (default marked with *)
ccs gemini --accounts
# Switch default
ccs gemini --use work
```
### Browser Doesn't Open
**Symptom:** OAuth flow stuck waiting for browser
**Solution:** Use headless mode:
```bash theme={null}
ccs gemini --headless
# Copy URL to browser manually
```
## Storage Locations
| Path | Description |
| ------------------------------------ | ------------------------------ |
| `~/.ccs/cliproxy/auth/gemini-*.json` | OAuth tokens (one per account) |
| `~/.ccs/cliproxy/accounts.json` | Account registry, nicknames |
| `~/.ccs/gemini.settings.json` | Model selection, preferences |
| `~/.ccs/cliproxy/config.yaml` | CLIProxy configuration |
## Cost Information
| Tier | Models | Cost |
| ---- | ---------------------------------------- | ---------------------------- |
| Free | Gemini 2.5 Pro, Gemini 3 Flash (limited) | \$0 |
| Paid | Gemini 3 Pro (High/Preview) | Google subscription required |
**Quota Management:** Automatic rotation if rate limited (config: `quota-exceeded.switch-project: true`)
## Advanced Features
### Token Structure
OAuth token file format (`gemini-{email}.json`):
```json theme={null}
{
"type": "gemini",
"access_token": "ya29...",
"refresh_token": "1//...",
"email": "user@gmail.com",
"expired": "2024-12-31T23:59:59Z",
"expiry_date": 1735689599000
}
```
### Proactive Refresh Logic
1. Before execution: Check `expiry_date`
2. If \< 5 minutes until expiry: Trigger refresh
3. If refresh succeeds: Update token file
4. If refresh fails: Prompt re-auth
5. Execute Claude CLI with valid token
**Why 5 minutes?** Matches CLIProxyAPI behavior, prevents race conditions during long API calls.
## Next Steps
Configure multiple Google accounts
Choose optimal Gemini model
Connect to external CLIProxy server
Enable Gemini-powered web search
# GitHub Copilot Provider (Deprecated)
Source: https://docs.ccs.kaitran.ca/providers/oauth/ghcp
Deprecated GitHub Copilot OAuth compatibility path with Device Code flow and rate limiting
# GitHub Copilot Provider (Deprecated)
Access GitHub Copilot models via OAuth Device Code flow for existing local
setups. This provider is now a deprecated compatibility path.
GitHub usage-based Copilot billing begins June 1, 2026. Existing CCS Copilot
setups remain available for compatibility, but new setups should prefer Codex
or another active provider.
## Compatibility Quick Start
```bash theme={null}
# First run (Device Code flow - no browser needed)
ccs ghcp "explain this code"
# Output:
# Visit: https://github.com/login/device
# Enter code: ABCD-1234
# Waiting for authorization...
```
## Authentication
### Device Code Flow
GitHub Copilot uses **Device Code flow** instead of browser OAuth - ideal for headless servers and remote machines.
Run `ccs ghcp "your prompt"`
CCS displays verification URL and user code
Open URL in any browser, enter code manually
CCS polls GitHub API, receives OAuth token when authorized
Token saved to `~/.ccs/cliproxy/auth/ghcp-{oauth}-{profile_id}.json`
Available since v7.37.1 - Device code and verification URL are also displayed in the CCS Dashboard for convenient access during authentication.
**Dashboard Display:**
* Device code shown with copy button
* Verification URL as clickable link
* 15-minute expiration timer countdown
* Auto-refresh on successful authorization
### Device Code vs Browser OAuth
GHCP uses Device Code flow because GitHub Copilot OAuth **does not support** callback servers.
| Feature | Device Code (GHCP) | Browser OAuth (Gemini/Codex) |
| ----------------- | ----------------------------- | ---------------------------- |
| Browser required? | No - works headless | Yes - opens automatically |
| User action | Copy code to browser manually | Click "Allow" in popup |
| Headless support | Native | Requires `--headless` flag |
| Callback server | None - polling only | Spawns local HTTP server |
### Authentication Commands
```bash theme={null}
# Trigger Device Code flow
ccs ghcp --auth
# Output:
# Visit: https://github.com/login/device
# Enter code: ABCD-1234
# Code expires in 15 minutes
# Waiting for authorization...
```
Complete authorization in any browser on any device - CCS polls GitHub API for token.
## Multi-Account Support
GitHub Copilot supports multiple accounts with **filename-based** identification:
```bash theme={null}
# Add second account
ccs ghcp --auth --add
# List accounts
ccs ghcp --accounts
# Output:
# Available GitHub Copilot accounts:
# * github-ABC123 (default)
# github-XYZ789
```
### Account Identification
**Pattern:** `ghcp-{oauth}-{profile_id}.json` → `{oauth}-{profile_id}`
**Example:**
* Token file: `ghcp-github-ABC123.json`
* Account ID: `github-ABC123`
* Nickname: Auto-generated or custom via `--nickname`
### Account Commands
```bash theme={null}
# Switch default account
ccs ghcp --use github-XYZ789
# Rename account
ccs ghcp --nickname work-copilot
# List all accounts
ccs ghcp --accounts
# Logout (clear tokens)
ccs ghcp --logout
```
## Configuration
### Config Keys
Configure via `~/.ccs/config.yaml`:
```yaml theme={null}
# GitHub Copilot settings
copilot:
account_type: "individual" # or "business"
rate_limit: 100 # Requests per hour
wait_on_limit: true # Wait vs fail on rate limit
# CLIProxy auth
cliproxy:
auth:
api_key: "ccs-internal-managed"
management_secret: "ccs"
```
### Account Types
| Type | Use Case | Rate Limits |
| ------------ | ----------------------------- | --------------- |
| `individual` | Personal Copilot subscription | Standard limits |
| `business` | GitHub Copilot for Business | Higher limits |
**Set account type:**
```yaml theme={null}
# ~/.ccs/config.yaml
copilot:
account_type: "business"
```
### Rate Limiting
GitHub Copilot has rate limits - configure behavior on limit:
```yaml theme={null}
copilot:
wait_on_limit: true
```
**Behavior:** CCS waits until rate limit resets, then retries
**Use Case:** Long-running sessions, non-interactive scripts
```yaml theme={null}
copilot:
wait_on_limit: false
```
**Behavior:** CCS exits immediately with error on rate limit
**Use Case:** Interactive sessions, user should know about limit
**Custom Rate Limit Threshold:**
```yaml theme={null}
copilot:
rate_limit: 200 # Requests per hour (default: 100)
```
### Environment Variables
Auto-managed by CCS. Manual override rarely needed.
```bash theme={null}
# Claude CLI injection (auto-set)
ANTHROPIC_BASE_URL=http://127.0.0.1:8317/api/provider/ghcp
ANTHROPIC_AUTH_TOKEN=ccs-internal-managed
ANTHROPIC_MODEL=claude-sonnet-5 # Dashboard default; editable in /cliproxy
```
## Commands Reference
### Basic Usage
```bash theme={null}
# Execute with GitHub Copilot
ccs ghcp "your prompt"
# One-shot mode
ccs ghcp "explain this function"
```
### Authentication Commands
```bash theme={null}
# Trigger Device Code flow
ccs ghcp --auth
# Add new account
ccs ghcp --auth --add
# Logout
ccs ghcp --logout
# No --headless flag needed (Device Code is headless-native)
```
### Account Management
```bash theme={null}
# List accounts
ccs ghcp --accounts
# Switch account
ccs ghcp --use github-XYZ789
# Rename account
ccs ghcp --nickname work-copilot
```
## Troubleshooting
### Improved OAuth Failure Diagnostics
Available since v7.51.0
CCS now provides specific, actionable error messages when GitHub Copilot OAuth fails — instead of generic "Token not found" errors.
**Before v7.51:** All auth failures showed `Token not found`
**After v7.51:** Specific errors surfaced from GitHub's OAuth flow:
| Error | Meaning | Action |
| ------------------------ | ---------------------------------- | ----------------------------- |
| `authorization_pending` | User hasn't completed login yet | Wait and retry |
| `slow_down` | Polling too fast | CCS handles automatically |
| `expired_token` | Device code expired (15 min limit) | Re-run `ccs ghcp --auth` |
| `access_denied` | User denied the authorization | Re-run and approve in browser |
| `unsupported_grant_type` | OAuth config issue | Contact support |
CCS strips ANSI escape codes and parses multi-line stderr from the GitHub OAuth flow, so errors from nested processes are surfaced cleanly in the terminal.
### Device Code Expired
**Symptom:** "Device code expired" error during authorization
**Cause:** User didn't complete authorization within 15 minutes
**Solution:** Re-run `--auth` to get new code:
```bash theme={null}
ccs ghcp --auth
# Complete authorization within 15 minutes
```
### Rate Limit Exceeded
**Symptom:** `429 Too Many Requests` error
**Cause:** Exceeded GitHub Copilot rate limit
**Solution 1:** Wait for rate limit reset (if `wait_on_limit: true`)
**Solution 2:** Configure wait behavior:
```yaml theme={null}
# ~/.ccs/config.yaml
copilot:
wait_on_limit: true # Auto-wait for reset
```
**Solution 3:** Increase rate limit threshold (Business accounts):
```yaml theme={null}
copilot:
rate_limit: 200 # Higher limit for Business tier
```
### Wrong Account Type
**Symptom:** Unexpected rate limits or quota errors
**Cause:** Account type mismatch (Individual vs Business)
**Solution:** Set correct account type:
```yaml theme={null}
# ~/.ccs/config.yaml
copilot:
account_type: "business" # or "individual"
```
### Token Refresh Failures
**Symptom:** "Unauthorized" errors after initial auth
**Cause:** OAuth token expired, refresh failed
**Solution:** Re-authenticate:
```bash theme={null}
ccs ghcp --auth
```
## Storage Locations
| Path | Description |
| ---------------------------------- | -------------------------------------------- |
| `~/.ccs/cliproxy/auth/ghcp-*.json` | OAuth tokens (one per account) |
| `~/.ccs/cliproxy/accounts.json` | Account registry, nicknames |
| `~/.ccs/cliproxy/config.yaml` | CLIProxy configuration |
| `~/.ccs/config.yaml` | Copilot settings (rate limits, account type) |
## Token Structure
GitHub Copilot OAuth token file format:
```json theme={null}
{
"type": "github-copilot",
"access_token": "gho_...",
"refresh_token": "ghr_...",
"expired": "2024-12-31T23:59:59Z"
}
```
**Filename Pattern:** `ghcp-{oauth}-{profile_id}.json`
**Account Identification:** Extracted from filename (no email field)
## Device Code Flow Details
### Authorization Flow
1. **CCS requests device code** from GitHub API
2. **GitHub returns:**
* `device_code` (internal use)
* `user_code` (user enters in browser)
* `verification_uri` (URL to visit)
* `interval` (polling frequency)
3. **User visits URL**, enters code manually
4. **CCS polls GitHub API** every `interval` seconds
5. **GitHub returns access token** when user completes authorization
6. **CCS caches token** to auth directory
### Polling Behavior
* **Interval:** 5 seconds (default from GitHub API)
* **Timeout:** 15 minutes (device code expiry)
* **Retry:** Stops on authorization or expiry
### No Callback Server Needed
Device Code flow eliminates need for:
* Local HTTP server
* Port availability
* Firewall configuration
* Localhost access
**Perfect for:**
* Headless servers
* Remote SSH sessions
* Docker containers
* CI/CD pipelines
## Rate Limiting Behavior
### Rate Limit Detection
CLIProxyAPI detects rate limits via:
* HTTP 429 status code
* `X-RateLimit-Remaining: 0` header
* `Retry-After` header
### Wait Strategy
When `wait_on_limit: true`:
1. **Detect rate limit** (429 response)
2. **Read `Retry-After` header** or calculate reset time
3. **Display wait message** with countdown
4. **Sleep until reset** (or user abort)
5. **Retry request** automatically
**User Experience:**
```bash theme={null}
ccs ghcp "long prompt"
# Output:
# [!] Rate limit exceeded
# [i] Waiting 47 minutes until reset at 14:30:00
# Press Ctrl+C to cancel
```
### Fail Fast Strategy
When `wait_on_limit: false`:
1. **Detect rate limit** (429 response)
2. **Display error message** with reset time
3. **Exit immediately** with exit code 6 (`PROVIDER_ERROR`)
**User Experience:**
```bash theme={null}
ccs ghcp "prompt"
# Output:
# [X] Rate limit exceeded
# [i] Limit resets at 14:30:00 (in 47 minutes)
# [i] Set copilot.wait_on_limit: true to auto-wait
```
## Quota Information
CCS tracks GitHub Copilot quota via `ccs cliproxy quota` and `ccs copilot usage`:
```bash theme={null}
ccs copilot usage
# Output:
# GitHub Copilot Usage
# Premium interactions: 42 / 300
# Chat: 128 / 500
# Completions: 2341 / unlimited
# Plan: individual
# Quota resets: 2026-03-01
```
| Quota Type | Description |
| --------------------- | -------------------------------------------- |
| `premiumInteractions` | High-capability model requests (Opus, GPT-5) |
| `chat` | Chat completions requests |
| `completions` | Code completions (usually unlimited) |
**Reset period:** Monthly (shown in `ccs copilot usage` output)
## Cost Information
| Tier | Cost | Rate Limits |
| ---------- | --------------- | --------------- |
| Individual | \$10/month | Standard limits |
| Business | \$19/user/month | Higher limits |
| Enterprise | Custom pricing | Custom limits |
**Rate Limits:**
* Individual: \~100 requests/hour
* Business: \~200 requests/hour (configurable)
* Exact limits set by GitHub, vary by account
## Advanced Features
### Model Mapping
GitHub Copilot models are configured from the CLIProxy provider editor:
* Open `ccs config` → **CLIProxy** → **GitHub Copilot (OAuth)**.
* Use **Model Config** to set the default, Opus, Sonnet, and Haiku routes.
* `claude-sonnet-5` is the default recommended GHCP model.
* If GitHub rolls out a model before CCS's static fallback catalog updates,
type the full model ID in the picker and select **Custom model**.
The selected IDs are written to `~/.ccs/ghcp.settings.json` as standard
`ANTHROPIC_MODEL` and `ANTHROPIC_DEFAULT_*_MODEL` values.
### Account Registry Integration
GHCP uses same multi-account system as other OAuth providers:
* Accounts stored in `~/.ccs/cliproxy/accounts.json`
* Nicknames auto-generated from account ID
* Default account tracked per provider
* `lastUsedAt` timestamp for analytics
### Session Persistence
GitHub Copilot sessions benefit from CLIProxy session persistence:
* First `ccs ghcp` spawns proxy (1-2s startup)
* Subsequent commands reuse existing proxy (instant)
* Proxy terminates when last session exits
* Version mismatch detection → auto-restart on upgrade
## Next Steps
Manage multiple GitHub accounts
Configure rate limit behavior
Understand headless authentication
Advanced CLIProxy settings
# GitLab Duo Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/gitlab
Use GitLab Duo through CCS with CLIProxy OAuth or PAT authentication
# GitLab Duo Provider
CCS supports **GitLab Duo** as a CLIProxy OAuth provider with two supported auth
paths:
* browser OAuth
* personal-access-token login (`--gitlab-token-login`)
## Quick Start
```bash theme={null}
# Standard GitLab.com OAuth
ccs gitlab --auth
# Use a GitLab Personal Access Token instead of browser OAuth
ccs gitlab --auth --gitlab-token-login
# Target a self-hosted GitLab instance
ccs gitlab --auth --gitlab-url https://gitlab.example.com
# Run through the provider after auth
ccs gitlab "summarize this merge request"
```
## Backend Requirement
GitLab Duo is a **plus-only** provider.
```yaml theme={null}
cliproxy:
backend: plus
```
## Authentication Details
| Path | Notes |
| ------------------ | -------------------------------------------------------------------------- |
| Browser OAuth | local callback flow on port `17171` |
| PAT login | use `--gitlab-token-login` or legacy alias `--token-login` |
| Self-hosted GitLab | pass `--gitlab-url `; CCS switches to paste-callback mode when needed |
## Useful Commands
```bash theme={null}
ccs gitlab --auth
ccs gitlab --auth --gitlab-token-login
ccs gitlab --auth --gitlab-url https://gitlab.example.com
ccs gitlab --accounts
ccs gitlab --use
ccs gitlab --config
ccs gitlab --logout
```
## Config And Storage
| Path | Purpose |
| ----------------------------- | ---------------------------------------------------- |
| `~/.ccs/cliproxy/auth/` | shared OAuth token directory |
| `~/.ccs/gitlab.settings.json` | provider settings when a local settings file is used |
## Notes
* Token refresh is delegated to CLIProxy
* model/config surfaces depend on what the upstream CLIProxy management API
exposes for the provider at runtime
## Related
* [Provider Overview](/providers/concepts/overview)
* [CLI Flags](/reference/cli-flags)
* [CLIProxy API](/features/proxy/cliproxy-api)
# iFlow Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/iflow
Access iFlow AI models via OAuth authentication
# iFlow Provider
Access iFlow AI models through Browser OAuth authentication. Seamless integration with Claude Code for instant model switching.
## Overview
The iFlow provider enables Claude Code to use iFlow's AI platform through Browser OAuth authentication with callback server on port 11451.
**Provider Identifier:** `iflow`
**Command:** `ccs iflow`
**Supported Models:**
* Various models available via iFlow platform
* Model selection configurable via CLIProxy settings
## Authentication
### First-Time Setup
```bash theme={null}
# Run iFlow for the first time
ccs iflow "review this code"
# Browser OAuth flow starts automatically
# → Browser opens for iFlow OAuth consent
# → Callback server spawns on port 11451
# → Token cached at ~/.ccs/cliproxy/auth/
# → Future runs require no re-auth
```
**Browser OAuth Flow:**
1. Authorization Code flow via browser callback
2. Callback server spawns on port 11451
3. Browser opens for iFlow OAuth consent
4. Token received via HTTP callback
5. Auto-refresh prevents mid-request failures
**Example Output:**
```
Authenticate with iFlow:
Opening browser for OAuth authentication...
Callback server listening on port 11451...
Browser opened for authentication.
```
### Manual Authentication
```bash theme={null}
# Authenticate without starting a session
ccs iflow --auth
# Headless mode (server/SSH environments)
ccs iflow --headless
# → Displays URL for manual browser authentication
# → Includes SSH tunnel instructions if needed
```
### Logout
```bash theme={null}
# Clear all iFlow tokens
ccs iflow --logout
```
## Multi-Account Support
Manage multiple iFlow accounts for different projects:
### Add Account
```bash theme={null}
# Add new account (preserves existing)
ccs iflow --auth --add
```
### List Accounts
```bash theme={null}
# Show all authenticated iFlow accounts
ccs iflow --accounts
# Output:
# Accounts for iflow:
# [default] work (work@company.com)
# personal (personal@example.com)
```
### Switch Account
```bash theme={null}
# Switch to specific account by nickname
ccs iflow --use personal
# Next command uses personal's account
ccs iflow "your prompt"
```
### Rename Account
```bash theme={null}
# Rename default account nickname
ccs iflow --nickname primary-account
```
**Account Registry:** `~/.ccs/cliproxy/accounts.json`
**Auto-Nicknames:** Generated from email prefix (e.g., `john@example.com` → `john`)
## Configuration Options
### Model Settings
iFlow provider settings stored in:
**Path:** `~/.ccs/iflow.settings.json`
**Configuration via Dashboard:**
```bash theme={null}
# Open web config interface
ccs config
# Navigate to CLIProxy → iFlow settings
```
**Manual Configuration:**
```json theme={null}
{
"env": {
"ANTHROPIC_MODEL": "iflow-model-name",
"ANTHROPIC_MAX_TOKENS": "8192"
}
}
```
### CLIProxy Integration
iFlow integrates with unified CLIProxy config:
**Path:** `~/.ccs/cliproxy/config.yaml`
**Provider Routing:** Requests routed to `/api/provider/iflow` endpoint
**Concurrent Usage:** Run iFlow + other providers simultaneously without conflicts
## Commands
### Basic Usage
```bash theme={null}
# Run with iFlow
ccs iflow "analyze this database schema"
# Interactive chat
ccs iflow
```
### Authentication Flags
| Flag | Description |
| -------------- | ------------------------------- |
| `--auth` | Trigger OAuth flow (no session) |
| `--logout` | Clear all tokens |
| `--auth --add` | Add new account (keep existing) |
### Account Management Flags
| Flag | Description |
| ------------------- | ---------------------- |
| `--accounts` | List all accounts |
| `--use ` | Switch default account |
| `--nickname ` | Rename default account |
## Storage Locations
| Path | Purpose |
| ----------------------------------- | ------------------------------- |
| `~/.ccs/cliproxy/auth/iflow-*.json` | OAuth tokens (one per account) |
| `~/.ccs/cliproxy/accounts.json` | Account registry with nicknames |
| `~/.ccs/iflow.settings.json` | Provider-specific settings |
| `~/.ccs/cliproxy/config.yaml` | CLIProxy unified config |
## Token Management
**Storage Format:**
```json theme={null}
{
"type": "iflow",
"access_token": "...",
"refresh_token": "...",
"email": "user@example.com",
"expired": "2024-12-31T23:59:59Z"
}
```
**Auto-Refresh:** Tokens managed by CLIProxyAPI
**Security:** Device Code flow prevents token interception (no callback server)
## Device Code Flow Details
**Why Device Code?**
* More secure (no callback server listening on local port)
* Works seamlessly in headless environments
* No port conflicts or firewall issues
* User completes auth on trusted device
**Flow Timeline:**
1. CCS requests device code from iFlow API
2. Displays code + URL to user
3. User authorizes in browser (any device)
4. CCS polls iFlow API for token availability
5. Token saved when authorization complete
**Callback Port:** `null` (no server required)
## Requirements
* iFlow subscription/account
* Browser for OAuth (on any device - not necessarily same machine)
* Network access to iFlow authentication servers
## Troubleshooting
### Device Code Expired
**Error:** "Device code expired before authorization"
**Solution:** Device codes expire after 10-15 minutes. Re-run `ccs iflow --auth` to get new code.
### Authorization Not Detected
```bash theme={null}
# Verify token file exists
ls ~/.ccs/cliproxy/auth/iflow-*.json
# Re-authenticate if missing
ccs iflow --logout
ccs iflow --auth
```
### Multi-Account Issues
```bash theme={null}
# List all accounts to verify state
ccs iflow --accounts
# Switch to specific account
ccs iflow --use
```
### Token Expiry
Tokens refresh automatically via CLIProxyAPI. If refresh fails:
```bash theme={null}
# Re-authenticate
ccs iflow --auth
```
## Model Alias Normalization
Available since v7.51.0
CCS automatically normalizes legacy iFlow model IDs to their canonical equivalents. This prevents 406/404 errors when iFlow's API updates model naming.
**Known mappings:**
| Legacy Model ID | Canonical Model ID |
| -------------------- | ------------------ |
| `kimi-k2.5` | `kimi-k2` |
| `deepseek-v3.2-chat` | `deepseek-v3.2` |
| `glm-4.7` | `glm-4.6` |
| `minimax-m2.5` | `qwen3-coder-plus` |
These mappings are applied automatically — no config change required. If you have `ANTHROPIC_MODEL` set to a legacy alias in your iFlow settings, it will continue to work.
## Cost Information
**iFlow Subscription/Account Required:** Check iflow\.ai for current pricing and subscription options
**Usage Limits:** Subject to iFlow's rate limits and subscription tier
## Next Steps
Manage multiple iFlow accounts
Configure via web interface
# Kilo AI Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/kilo
Use Kilo AI through CCS as a CLIProxy device-code provider
# Kilo AI Provider
CCS supports **Kilo AI** as a CLIProxy provider.
## Quick Start
```bash theme={null}
ccs kilo --auth
ccs kilo --accounts
ccs kilo --config
ccs kilo "explain this error"
```
## Authentication Model
Kilo uses a **device-code flow**:
* no local callback port is required
* the auth flow is device-code based rather than browser callback based
* CCS currently treats token refresh as unsupported, so re-run `ccs kilo --auth`
if upstream auth expires
## Backend Requirement
Kilo is a **plus-only** provider.
```yaml theme={null}
cliproxy:
backend: plus
```
## Config And Storage
| Path | Purpose |
| --------------------------- | ---------------------------------------------------- |
| `~/.ccs/cliproxy/auth/` | shared OAuth token directory |
| `~/.ccs/kilo.settings.json` | provider settings when a local settings file is used |
## Related
* [Provider Overview](/providers/concepts/overview)
* [CLIProxy API](/features/proxy/cliproxy-api)
# Kimi Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/kimi
Moonshot AI K2/K2.5 models via OAuth (CLIProxy) or API key direct (km)
# Kimi Provider
CCS provides two distinct Kimi offerings:
| Command | Auth | Endpoint | Use Case |
| ---------- | -------------------------------- | ----------------------------------------- | -------------------------------- |
| `ccs kimi` | OAuth via CLIProxy (device code) | `http://127.0.0.1:8317/api/provider/kimi` | Multi-account, no API key needed |
| `ccs km` | API key direct | `https://api.kimi.com/coding/` | Single API key, Kimi for Coding |
Provider aliases: `kimi`, `moonshot` both route to the same CLIProxy provider.
## Quick Start
```bash theme={null}
# OAuth mode (CLIProxy) — no API key needed
ccs kimi "explain this code"
# API preset mode — requires API key (Kimi for Coding)
ccs km "explain this code"
# List accounts (OAuth mode)
ccs kimi --accounts
# Switch account
ccs kimi --use work
```
## Authentication
### `ccs kimi` — OAuth Mode (CLIProxy)
Run `ccs kimi --kimi-login` — device code displayed in terminal
Visit the URL shown and enter the device code (no callback port needed)
OAuth token saved to `~/.ccs/cliproxy/auth/kimi-{email}.json`
CLIProxy backend manages token refresh automatically
**Device Code Flow:** Polling-based authentication — no local callback server required. Works in headless/server environments.
### `ccs km` — API Key Mode (Kimi for Coding)
Obtain a `sk-...` key from Moonshot AI platform
Run `ccs km` — prompted for API key on first use
All requests use extended thinking by default
`ccs km` connects directly to `https://api.kimi.com/coding/`. Default model: `kimi-for-coding`. The `--preset kimi` flag auto-maps to `km` for backward compatibility.
## Multi-Account Support
```bash theme={null}
# Add second Kimi account (preserves existing)
ccs kimi --kimi-login --add
# Auto-nicknamed from email prefix
```
```bash theme={null}
ccs kimi --accounts
# Output:
# Available Kimi accounts:
# * personal (user@email.com) - default
# work (work@email.com)
```
```bash theme={null}
# Switch default account
ccs kimi --use work
# Rename current account
ccs kimi --nickname personal
```
**Account Registry:** `~/.ccs/cliproxy/accounts.json` — aliases `kimi` and `moonshot` both map to the same provider.
## Model Configuration
### Available Models
#### `ccs kimi` (CLIProxy OAuth)
| Model | Context | Notes |
| ------------------ | ------- | --------------------------- |
| `kimi-k2.5` | 262K | Default — latest multimodal |
| `kimi-k2-thinking` | — | Extended reasoning |
| `kimi-k2` | — | Flagship coding model |
#### `ccs km` (API key direct)
| Model | Notes |
| ----------------- | ---------------------- |
| `kimi-for-coding` | Default model for `km` |
**Thinking budget:** 1K–32K tokens, dynamic and zero allowed.
**Vision:** Configurable via `vision-model` placeholder in settings.
### Settings Template
Settings saved to `~/.ccs/km.settings.json` from `base-km.settings.json`:
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.kimi.com/coding/",
"ANTHROPIC_AUTH_TOKEN": "YOUR_KIMI_API_KEY_HERE",
"ANTHROPIC_MODEL": "kimi-for-coding",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "kimi-for-coding",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-for-coding",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "kimi-for-coding"
}
}
```
These env vars are injected automatically by CCS. Manual override is rarely needed.
## Commands Reference
```bash theme={null}
# Basic usage
ccs kimi "your prompt"
ccs km "your prompt" # API preset
# Authentication
ccs kimi --kimi-login # Trigger device code OAuth
ccs kimi --kimi-login --add # Add second account
ccs kimi --logout # Clear tokens
# Account management
ccs kimi --accounts # List all accounts
ccs kimi --use work # Switch default account
ccs kimi --nickname personal # Rename current account
```
## Troubleshooting
### Device Code Expired
**Symptom:** "Device code expired" error during login
**Solution:** Device codes have a short TTL. Re-run login and complete quickly:
```bash theme={null}
ccs kimi --logout
ccs kimi --kimi-login
```
### API Key Rejected (km mode)
**Symptom:** 401 errors when using `ccs km`
**Solution:** Verify key format (`sk-...`) and permissions on Moonshot AI platform.
API keys for `ccs km` are separate from OAuth tokens used by `ccs kimi`. Do not mix them.
### Wrong Account Active
**Symptom:** Unexpected account being used
**Solution:**
```bash theme={null}
# Check default (marked with *)
ccs kimi --accounts
# Switch default
ccs kimi --use work
```
## Storage Locations
| Path | Description |
| ---------------------------------- | ------------------------------ |
| `~/.ccs/cliproxy/auth/kimi-*.json` | OAuth tokens (one per account) |
| `~/.ccs/cliproxy/accounts.json` | Account registry, nicknames |
| `~/.ccs/km.settings.json` | Kimi for Coding model config |
## Cost Information
| Model | Input/M | Output/M | Cache/M |
| ------------------ | ------- | -------- | ------- |
| `kimi-k2.5` | \$0.60 | \$3.00 | \$0.10 |
| `kimi-k2-thinking` | \$0.60 | \$2.50 | \$0.15 |
| `kimi-for-coding` | \$0.60 | \$2.50 | \$0.15 |
| `kimi-k2` | \$0.60 | \$2.50 | \$0.15 |
## Next Steps
Manage multiple Kimi accounts
Configure direct API key access
Connect to external CLIProxy server
Explore other supported providers
# Kiro Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/kiro
Kiro OAuth with Builder ID, IDC, token import, and browser-mode control
# Kiro Provider
Access Kiro through CCS with AWS Builder ID, IAM Identity Center (IDC), and
token-import flows. CCS also adds browser-mode control and multi-account
management on top of the upstream auth paths.
## Quick Start
```bash theme={null}
# Default Builder ID flow
ccs kiro --auth
# AWS Builder ID auth-code flow with manual callback paste
ccs kiro --auth --kiro-auth-method aws-authcode --paste-callback
# IAM Identity Center (IDC) flow
ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start
# Import an existing token from Kiro IDE
ccs kiro --import
```
Kiro provides a free tier via AWS Builder ID, so the default `aws` path is the
best starting point for most users.
## Authentication
### Auth Methods
| Method | Availability | Typical use |
| -------------- | --------------------------------- | ------------------------------------------------------- |
| `aws` | CLI + dashboard | Default AWS Builder ID device-code flow |
| `aws-authcode` | CLI + dashboard | AWS Builder ID auth-code flow via local callback server |
| `google` | CLI + dashboard | Google OAuth auth-code flow |
| `idc` | CLI + dashboard | IAM Identity Center with required start URL |
| `github` | Dashboard account-management flow | Management-only social OAuth flow |
The default `ccs kiro --auth` path is `aws`. When upstream shows a Builder ID
vs IDC chooser, CCS auto-selects the Builder ID option instead of waiting for
manual input.
### Callback And Paste-Callback
Callback-based methods can use `--paste-callback` when CCS cannot receive the
redirect directly:
```bash theme={null}
ccs kiro --auth --kiro-auth-method aws-authcode --paste-callback
ccs kiro --auth --kiro-auth-method google --paste-callback
```
Use this when you are authenticating through SSH, reverse proxies, or other
environments where the local callback listener is blocked.
### IDC
IDC requires a start URL:
```bash theme={null}
ccs kiro --auth --kiro-auth-method idc \
--kiro-idc-start-url https://d-xxx.awsapps.com/start
```
Optional IDC flags:
```bash theme={null}
ccs kiro --auth --kiro-auth-method idc \
--kiro-idc-start-url https://d-xxx.awsapps.com/start \
--kiro-idc-region us-east-1 \
--kiro-idc-flow device
```
`--kiro-idc-flow` defaults to `authcode`. Use `device` only when you
intentionally want the device-code variant.
## Browser Mode
Kiro defaults to normal browser mode in current CCS releases:
```yaml theme={null}
cliproxy:
kiro_no_incognito: true
```
That keeps AWS login state available for re-auth and avoids common Linux
incognito failures. Use `--no-incognito` when you want to make that choice
explicit from the CLI.
## Token Import From Kiro IDE
```bash theme={null}
ccs kiro --import
```
CCS scans the local Kiro IDE installation, copies the token into
`~/.ccs/cliproxy/auth/`, and registers the account for normal CCS usage.
Import is the fastest recovery path when Kiro IDE is already authenticated.
## Multi-Account Support
Kiro accounts use filename-derived identifiers instead of email:
```bash theme={null}
ccs kiro --auth --add
ccs kiro --accounts
ccs kiro --use github-XYZ789
ccs kiro --nickname work-aws
ccs kiro --logout
```
This keeps account identity stable even when the provider does not expose an
email address.
## Configuration
```yaml theme={null}
cliproxy:
kiro_no_incognito: true
auth:
api_key: "ccs-internal-managed"
management_secret: "ccs"
```
## Commands Reference
```bash theme={null}
# Start default Builder ID auth
ccs kiro --auth
# Use a specific CLI auth method
ccs kiro --auth --kiro-auth-method aws-authcode
ccs kiro --auth --kiro-auth-method google
ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start
# Use manual callback paste for callback-based methods
ccs kiro --auth --kiro-auth-method aws-authcode --paste-callback
# Import from IDE instead of browser auth
ccs kiro --import
```
GitHub-backed Kiro account addition is handled from the dashboard account flow,
not from the direct CLI launch path.
## Troubleshooting
### Kiro auth keeps failing on Linux
* Keep `cliproxy.kiro_no_incognito: true`
* Prefer the Builder ID device flow first: `ccs kiro --auth`
* Use `--paste-callback` for callback-based flows when redirects cannot reach CCS
### IDC fails immediately
* Make sure `--kiro-idc-start-url` is present
* Check that the start URL belongs to the expected AWS Identity Center tenant
* Try `--kiro-idc-flow device` if authcode flow is blocked in your environment
### Import cannot find a token
* Confirm Kiro IDE is installed and already authenticated
* If import still fails, fall back to `ccs kiro --auth`
### The wrong account is being used
* Run `ccs kiro --accounts`
* Switch with `ccs kiro --use `
* Rename the intended account with `ccs kiro --nickname ` if the current
filename-derived ID is too ambiguous
## Next Steps
* [Provider Overview](/providers/concepts/overview)
* [CLI Commands](/reference/cli-commands)
* [CLI Flags](/reference/cli-flags)
* [Headless Workflow](/features/workflow/headless-workflow)
# Qoder Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/qoder
Use Qoder through CCS as a CLIProxy device-code provider
# Qoder Provider
CCS supports **Qoder** as a CLIProxy provider for AI coding workflows.
## Quick Start
```bash theme={null}
ccs qoder --auth
ccs qoder --accounts
ccs qoder --config
ccs qoder "review this change"
```
## Authentication Model
Qoder uses a **device-code flow**:
* no local callback port is required
* CCS opens or prints the Qoder device login URL
* CCS currently treats token refresh as unsupported, so re-run `ccs qoder --auth`
if upstream auth expires
## Model Selection
Qoder supports the interactive model picker:
```bash theme={null}
ccs qoder --config
```
The default route is `qoder/auto`. The static fallback catalog also includes
Qoder tier routes such as `qoder/ultimate`, `qoder/performance`,
`qoder/efficient`, and `qoder/lite`.
## Backend Requirement
Qoder is a **plus-only** provider.
```yaml theme={null}
cliproxy:
backend: plus
```
## Config And Storage
| Path | Purpose |
| ---------------------------- | ---------------------------------------------------- |
| `~/.ccs/cliproxy/auth/` | shared OAuth token directory |
| `~/.ccs/qoder.settings.json` | provider settings when a local settings file is used |
## Related
* [Provider Overview](/providers/concepts/overview)
* [CLIProxy API](/features/proxy/cliproxy-api)
# Qwen Provider Status
Source: https://docs.ccs.kaitran.ca/providers/oauth/qwen
Qwen account linking is currently unavailable in the bundled CLIProxy runtime
# Qwen Provider Status
Qwen account linking is currently unavailable in the bundled CLIProxy runtime.
Commands such as `ccs qwen --auth` and `ccs qwen --auth --add` return a clear
unsupported-provider error instead of starting a broken device-code flow.
The upstream CLIProxy runtime bundled with CCS does not expose Qwen OAuth or
device-code authentication. Use an API-key Qwen route instead.
## Recommended Qwen Route
Use [Alibaba Coding Plan](/providers/api/alibaba) for Qwen3 Coder models with an
API key:
```bash theme={null}
ccs api create --preset alibaba-coding-plan
ccs albb "review this function"
```
This keeps Qwen model access available while avoiding the unsupported account
linking path.
## Unsupported Commands
```bash theme={null}
ccs qwen --auth
ccs qwen --auth --add
ccs qwen --use
```
These commands depend on runtime-managed Qwen OAuth tokens, which CLIProxy does
not provide today.
## Related Pages
Use Qwen3 Coder models with an API key
Configure API-key providers and custom endpoints
# xAI (Grok) Provider
Source: https://docs.ccs.kaitran.ca/providers/oauth/xai
Use xAI Grok through CCS as a CLIProxy device-code OAuth provider
# xAI (Grok) Provider
CCS supports **xAI (Grok)** through CLIProxy OAuth. The canonical provider ID
is `xai`; `grok` is a supported CLI alias for the same provider state.
## Quick Start
```bash theme={null}
ccs xai --auth
ccs xai --accounts
ccs xai --config
ccs xai "review this change"
ccs grok "review this change" # equivalent shortcut
```
Use `xai` in configuration and provider references. `grok` does not create a
separate account bucket, settings file, or model catalog.
## Authentication
xAI uses a **device-code OAuth flow**:
* Run `ccs xai --auth`, then complete authorization at the displayed xAI
device URL with its verification code.
* No local callback port is used.
* `ccs xai --auth --headless` avoids launching a browser; it still displays
the device URL and code, then polls for completion.
* CLIProxy manages token refresh after authorization.
`ccs grok --auth` starts the same OAuth flow. This provider shortcut is
separate from standalone API-key Grok integrations, including Grok WebSearch
or Docker CLI configuration.
## Accounts And Storage
xAI supports multiple accounts. CCS uses token metadata email when it is
available; otherwise it derives a stable account ID from the `xai-*.json`
filename suffix. If an ID collides, CCS uses `xai-1`, `xai-2`, and so on.
| Path | Purpose |
| --------------------------------- | -------------------------------------- |
| `~/.ccs/cliproxy/auth/xai-*.json` | xAI OAuth token files |
| `~/.ccs/cliproxy/accounts.json` | account registry under `providers.xai` |
| `~/.ccs/xai.settings.json` | local xAI provider settings when used |
```bash theme={null}
ccs xai --accounts
ccs xai --use
ccs xai --auth --add
ccs xai --logout
```
## Model Selection
Use the interactive picker to choose a configured route:
```bash theme={null}
ccs xai --config
```
The default is `grok-build-0.1`. When a live CLIProxy catalog is available it
is used first, followed by an unexpired local cache; the bundled static
catalog is a fallback when neither is usable.
The bundled static fallback catalog contains:
* `grok-build-0.1`
* `grok-4.5`
* `grok-4.3`
* `grok-4.20-0309-reasoning`
* `grok-4.20-0309-non-reasoning`
* `grok-4.20-multi-agent-0309`
* `grok-3-mini`
* `grok-3-mini-fast`
* `grok-composer-2.5-fast`
The default tier mapping is `grok-build-0.1` for default and Sonnet,
`grok-4.5` for Opus, and `grok-composer-2.5-fast` for Haiku.
### Dashboard Reasoning Selector
In `ccs config`, each xAI tier in the CLIProxy model mapping shows a reasoning
dropdown when the selected catalog model advertises supported levels:
| Model | Choices |
| ---------- | ----------------------------------------- |
| `grok-4.5` | **Auto**, `low`, `medium`, `high` |
| `grok-4.3` | **Auto**, `none`, `low`, `medium`, `high` |
**Auto** removes the parenthesized reasoning suffix. Other choices add an
explicit suffix, such as `grok-4.5(high)` or `grok-4.3(none)`; `none` is an
explicit setting, not the same as **Auto**.
## Backend Compatibility
xAI works with the default `original` CLIProxy backend as well as `plus`; it
is not a Plus-only provider. xAI does not participate in the CLIProxy quota
display.
## Related
* [Provider Overview](/providers/concepts/overview)
* [CLIProxy API](/features/proxy/cliproxy-api)
* [CLI Commands](/reference/cli-commands)
# CLIProxy Control API
Source: https://docs.ccs.kaitran.ca/reference/api-cliproxy
REST API endpoints for managing CLIProxyAPI service, models, and configurations
# CLIProxy Control API
Control the CLIProxyAPI service lifecycle, manage OAuth accounts, and access provider-specific features. CLIProxy enables OAuth authentication for Gemini, Codex, Antigravity, and other AI providers.
## Overview
CLIProxy endpoints provide:
* Service start/stop control
* Proxy health status monitoring
* Model listing and configuration
* Error log access
* Config file management
* Auth file downloads
* Provider quota queries
## Authentication
All endpoints are available on localhost only ([http://localhost:3000](http://localhost:3000)). No authentication required.
## Service Control
### GET /api/cliproxy/proxy-status
Get detailed proxy process status including PID, port, and session count.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/proxy-status
```
```json Response (Running) theme={null}
{
"running": true,
"port": 8317,
"pid": 12345,
"sessionCount": 3,
"startedAt": 1704460000000
}
```
```json Response (Not Running) theme={null}
{
"running": false
}
```
**Response Fields:**
* `running`: Service status (boolean)
* `port`: Local proxy port (default: 8317)
* `pid`: Process ID
* `sessionCount`: Active CLIProxy sessions
* `startedAt`: Timestamp when service started
***
### POST /api/cliproxy/proxy-start
Start the CLIProxy service in background.
```bash Request theme={null}
curl -X POST http://localhost:3000/api/cliproxy/proxy-start
```
```json Response (Started) theme={null}
{
"started": true,
"alreadyRunning": false,
"port": 8317
}
```
```json Response (Already Running) theme={null}
{
"started": false,
"alreadyRunning": true,
"port": 8317
}
```
***
### POST /api/cliproxy/proxy-stop
Stop the CLIProxy service.
```bash Request theme={null}
curl -X POST http://localhost:3000/api/cliproxy/proxy-stop
```
```json Response theme={null}
{
"stopped": true,
"pid": 12345,
"sessionCount": 3
}
```
***
### GET /api/cliproxy/update-check
Check for CLIProxyAPI binary updates.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/update-check
```
```json Response (Update Available) theme={null}
{
"hasUpdate": true,
"currentVersion": "1.5.0",
"latestVersion": "1.6.0",
"fromCache": false
}
```
```json Response (Up to Date) theme={null}
{
"hasUpdate": false,
"currentVersion": "1.6.0",
"latestVersion": "1.6.0",
"fromCache": true
}
```
## Model Management
### GET /api/cliproxy/models
Get available models from CLIProxyAPI `/v1/models` endpoint.
Requires CLIProxy service to be running. Returns 503 if service is down.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/models
```
```json Response theme={null}
{
"models": [
{
"id": "claude-sonnet-4",
"object": "model",
"created": 1704460000,
"owned_by": "anthropic"
},
{
"id": "gemini-3-flash-preview",
"object": "model",
"created": 1704460000,
"owned_by": "google"
}
],
"byCategory": {
"anthropic": [...],
"google": [...]
},
"totalCount": 42
}
```
```json Error (Service Down) theme={null}
{
"error": "CLIProxy Plus not running",
"message": "Start a CLIProxy session (gemini, codex, agy) to fetch available models"
}
```
## Error Logs
### GET /api/cliproxy/error-logs
List error log files with metadata extraction (status code, model).
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/error-logs
```
```json Response theme={null}
{
"files": [
{
"name": "error-2026-01-05T14-30-00.log",
"size": 4096,
"mtime": 1704467400000,
"absolutePath": "/home/user/.ccs/cliproxy/logs/error-2026-01-05T14-30-00.log",
"statusCode": 429,
"model": "gemini-3-flash-preview"
}
]
}
```
**Metadata Fields:**
* `statusCode`: Extracted from response section (e.g., 429, 500)
* `model`: Extracted from request body (e.g., "gemini-3-flash-preview")
***
### GET /api/cliproxy/error-logs/:name
Get full content of a specific error log.
**Path Parameters:**
* `name`: Error log filename (e.g., `error-2026-01-05T14-30-00.log`)
Filename must match pattern `error-*.log` and cannot contain path traversal characters.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/error-logs/error-2026-01-05T14-30-00.log
```
```text Response theme={null}
=== Request ===
POST /v1/messages HTTP/1.1
Content-Type: application/json
{"model":"gemini-3-flash-preview","messages":[...]}
=== Response ===
Status: 429
{"error":{"type":"rate_limit_error","message":"Rate limit exceeded"}}
```
## Configuration
### GET /api/cliproxy/config.yaml
Get CLIProxy YAML configuration content.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/config.yaml
```
```yaml Response theme={null}
server:
port: 8317
host: 127.0.0.1
auth:
api_key: "your-api-key"
management_secret: "your-secret"
providers:
gemini:
enabled: true
oauth_port: 8318
codex:
enabled: true
oauth_port: 8319
```
***
### PUT /api/cliproxy/config.yaml
Save CLIProxy YAML configuration with atomic write (temp file + rename).
```bash Request theme={null}
curl -X PUT http://localhost:3000/api/cliproxy/config.yaml \
-H "Content-Type: application/json" \
-d '{"content":"server:\n port: 8317\n host: 127.0.0.1"}'
```
```json Response theme={null}
{
"success": true,
"path": "/home/user/.ccs/cliproxy/config.yaml"
}
```
## Auth Files
### GET /api/cliproxy/auth-files
List auth files in `~/.ccs/cliproxy/auth/` directory.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/auth-files
```
```json Response theme={null}
{
"files": [
{
"name": "user@gmail.com-project123.json",
"size": 2048,
"mtime": 1704467400000
},
{
"name": "codex-user@email.com.json",
"size": 1536,
"mtime": 1704467300000
}
],
"directory": "/home/user/.ccs/cliproxy/auth"
}
```
***
### GET /api/cliproxy/auth-files/download
Download auth file content as octet-stream.
**Query Parameters:**
* `name`: Auth filename (e.g., `user@gmail.com-project123.json`)
```bash Request theme={null}
curl "http://localhost:3000/api/cliproxy/auth-files/download?name=user@gmail.com-project123.json" \
-o auth-file.json
```
```json Response theme={null}
{
"access_token": "ya29...",
"refresh_token": "1//...",
"scope": "https://www.googleapis.com/auth/cloud-platform",
"token_type": "Bearer",
"expiry_date": 1704471000000
}
```
## Provider Quota
### GET /api/cliproxy/quota/:provider/:accountId
Get quota information for a specific provider account.
**Path Parameters:**
* `provider`: Provider name (agy, gemini, codex, iflow, kiro, ghcp)
* `accountId`: Account identifier
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/quota/gemini/user@gmail.com-project123
```
```json Response theme={null}
{
"provider": "gemini",
"accountId": "user@gmail.com-project123",
"quotas": [
{
"model": "gemini-3-flash-preview",
"limit": 1000000,
"used": 450000,
"remaining": 550000,
"resetAt": 1704510000000
},
{
"model": "gemini-3-pro-preview",
"limit": 500000,
"used": 200000,
"remaining": 300000,
"resetAt": 1704510000000
}
]
}
```
```json Error (Invalid Provider) theme={null}
{
"error": "Invalid provider",
"message": "Provider must be one of: agy, gemini, codex, iflow, kiro, ghcp"
}
```
## Error Responses
```json 400 Bad Request theme={null}
{
"error": "Missing required field: content"
}
```
```json 404 Not Found theme={null}
{
"error": "Config file not found"
}
```
```json 500 Server Error theme={null}
{
"error": "Failed to write config file",
"message": "Detailed error message"
}
```
```json 503 Service Unavailable theme={null}
{
"error": "CLIProxy Plus not running",
"message": "Start a CLIProxy session to access this endpoint"
}
```
## Security Notes
* **Path Traversal Protection**: All file operations validate filenames to prevent `../` attacks
* **Atomic Writes**: Config updates use temp file + rename for crash safety
* **Localhost Only**: API only accessible on 127.0.0.1
* **No External Access**: CLIProxy management API requires local network access
# Settings & Auth API
Source: https://docs.ccs.kaitran.ca/reference/api-settings
REST API endpoints for managing profile settings, presets, and authentication tokens
# Settings & Auth API
Manage profile settings, create presets for quick configuration switching, and control global authentication tokens for CLIProxy.
## Overview
Settings endpoints provide:
* Profile settings CRUD (Create, Read, Update, Delete)
* Preset management for model configurations
* Global auth token management (API key, management secret)
* Token regeneration and reset
* Conflict detection with optimistic locking
## Authentication
All endpoints are available on localhost only ([http://localhost:3000](http://localhost:3000)). No authentication required.
## Profile Settings
### GET /api/settings/:profile
Get settings for a profile with masked API keys.
**Path Parameters:**
* `profile`: Profile name or variant (e.g., `gemini`, `glm`, `agy`)
```bash Request theme={null}
curl http://localhost:3000/api/settings/gemini
```
```json Response theme={null}
{
"profile": "gemini",
"settings": {
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8317/api/provider/gemini",
"ANTHROPIC_AUTH_TOKEN": "********",
"ANTHROPIC_MODEL": "gemini-3-flash-preview"
}
},
"mtime": 1704467400000,
"path": "/home/user/.ccs/gemini.settings.json"
}
```
```json Error (Not Found) theme={null}
{
"error": "Settings not found"
}
```
**Note:** Sensitive keys (API tokens, secrets) are automatically masked with `********`.
***
### GET /api/settings/:profile/raw
Get full unmasked settings for editing.
Sensitive endpoint - returns unmasked API keys. Use for editing only.
```bash Request theme={null}
curl http://localhost:3000/api/settings/gemini/raw
```
```json Response theme={null}
{
"profile": "gemini",
"settings": {
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8317/api/provider/gemini",
"ANTHROPIC_AUTH_TOKEN": "actual-token-here",
"ANTHROPIC_MODEL": "gemini-3-flash-preview"
}
},
"mtime": 1704467400000,
"path": "/home/user/.ccs/gemini.settings.json"
}
```
***
### PUT /api/settings/:profile
Update settings with conflict detection and automatic backup.
**Path Parameters:**
* `profile`: Profile name or variant
**Request Body:**
* `settings` (required): Settings object with `env` field
* `expectedMtime` (optional): Timestamp for optimistic locking
```bash Request theme={null}
curl -X PUT http://localhost:3000/api/settings/gemini \
-H "Content-Type: application/json" \
-d '{
"settings": {
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8317/api/provider/gemini",
"ANTHROPIC_AUTH_TOKEN": "new-token",
"ANTHROPIC_MODEL": "gemini-3-pro-preview"
}
},
"expectedMtime": 1704467400000
}'
```
```json Response (Success) theme={null}
{
"profile": "gemini",
"mtime": 1704467500000,
"backupPath": "/home/user/.ccs/backups/gemini.2026-01-05T14-30-00.settings.json",
"created": false
}
```
```json Response (New File) theme={null}
{
"profile": "glm",
"mtime": 1704467500000,
"created": true,
"warning": "Missing fields will use defaults: ANTHROPIC_BASE_URL",
"missingFields": ["ANTHROPIC_BASE_URL"]
}
```
```json Error (Conflict) theme={null}
{
"error": "File modified externally",
"currentMtime": 1704467450000
}
```
**Features:**
* **Optimistic Locking**: Uses `expectedMtime` to detect concurrent edits
* **Automatic Backup**: Creates backup before modification in `~/.ccs/backups/`
* **Atomic Write**: Temp file + rename for crash safety
* **Validation Warning**: Alerts if required fields missing (non-blocking)
## Presets
### GET /api/settings/:profile/presets
Get saved presets for a profile.
```bash Request theme={null}
curl http://localhost:3000/api/settings/gemini/presets
```
```json Response theme={null}
{
"presets": [
{
"name": "Opus Thinking",
"default": "gemini-claude-opus-4-5-thinking",
"opus": "gemini-claude-opus-4-5-thinking",
"sonnet": "gemini-claude-opus-4-5-thinking",
"haiku": "gemini-3-flash-preview"
},
{
"name": "Balanced",
"default": "gemini-claude-sonnet-4",
"opus": "gemini-claude-opus-4-5",
"sonnet": "gemini-claude-sonnet-4",
"haiku": "gemini-claude-haiku-4"
}
]
}
```
***
### POST /api/settings/:profile/presets
Create a new preset configuration.
**Request Body:**
* `name` (required): Preset name
* `default` (required): Default model
* `opus` (optional): Opus tier model
* `sonnet` (optional): Sonnet tier model
* `haiku` (optional): Haiku tier model
```bash Request theme={null}
curl -X POST http://localhost:3000/api/settings/gemini/presets \
-H "Content-Type: application/json" \
-d '{
"name": "Custom Mix",
"default": "gemini-claude-sonnet-4",
"opus": "gemini-claude-opus-4-5",
"sonnet": "gemini-claude-sonnet-4",
"haiku": "gemini-3-flash-preview"
}'
```
```json Response (Created) theme={null}
{
"preset": {
"name": "Custom Mix",
"default": "gemini-claude-sonnet-4",
"opus": "gemini-claude-opus-4-5",
"sonnet": "gemini-claude-sonnet-4",
"haiku": "gemini-3-flash-preview"
}
}
```
```json Error (Duplicate) theme={null}
{
"error": "Preset with this name already exists"
}
```
***
### DELETE /api/settings/:profile/presets/:name
Delete a preset by name.
```bash Request theme={null}
curl -X DELETE http://localhost:3000/api/settings/gemini/presets/Custom%20Mix
```
```json Response theme={null}
{
"success": true
}
```
```json Error (Not Found) theme={null}
{
"error": "Preset not found"
}
```
## Global Auth Tokens
### GET /api/settings/auth/tokens
Get current auth token status with masked values.
```bash Request theme={null}
curl http://localhost:3000/api/settings/auth/tokens
```
```json Response theme={null}
{
"apiKey": {
"value": "ccs_********************************",
"isCustom": false
},
"managementSecret": {
"value": "********",
"isCustom": true
}
}
```
**Fields:**
* `isCustom`: `true` if user-provided, `false` if default
***
### GET /api/settings/auth/tokens/raw
Get unmasked auth tokens.
Sensitive endpoint - returns unmasked secrets. No caching headers applied.
```bash Request theme={null}
curl http://localhost:3000/api/settings/auth/tokens/raw
```
```json Response theme={null}
{
"apiKey": {
"value": "ccs_1234567890abcdef1234567890abcdef",
"isCustom": false
},
"managementSecret": {
"value": "my-secret-key-12345",
"isCustom": true
}
}
```
***
### PUT /api/settings/auth/tokens
Update global auth tokens and regenerate CLIProxy config.
**Request Body:**
* `apiKey` (optional): New API key (empty string to reset to default)
* `managementSecret` (optional): New management secret
```bash Request theme={null}
curl -X PUT http://localhost:3000/api/settings/auth/tokens \
-H "Content-Type: application/json" \
-d '{
"apiKey": "ccs_new-api-key-here",
"managementSecret": "new-secret-123"
}'
```
```json Response theme={null}
{
"success": true,
"apiKey": {
"value": "ccs_********************************",
"isCustom": true
},
"managementSecret": {
"value": "********",
"isCustom": true
},
"message": "Restart CLIProxy to apply changes"
}
```
Changes require CLIProxy restart to take effect. Config is regenerated automatically.
***
### POST /api/settings/auth/tokens/regenerate-secret
Generate a new 32-character management secret.
```bash Request theme={null}
curl -X POST http://localhost:3000/api/settings/auth/tokens/regenerate-secret
```
```json Response theme={null}
{
"success": true,
"managementSecret": {
"value": "********",
"isCustom": true
},
"message": "Restart CLIProxy to apply changes"
}
```
***
### POST /api/settings/auth/tokens/reset
Reset auth tokens to defaults.
```bash Request theme={null}
curl -X POST http://localhost:3000/api/settings/auth/tokens/reset
```
```json Response theme={null}
{
"success": true,
"apiKey": {
"value": "ccs_********************************",
"isCustom": false
},
"managementSecret": {
"value": "********",
"isCustom": false
},
"message": "Tokens reset to defaults. Restart CLIProxy to apply."
}
```
## Account Management
### DELETE /api/accounts/reset-default
Reset default account to CCS default.
```bash Request theme={null}
curl -X DELETE http://localhost:3000/api/accounts/reset-default
```
```json Response theme={null}
{
"success": true,
"message": "Default account reset to CCS"
}
```
## Error Responses
```json 400 Bad Request theme={null}
{
"error": "settings object is required in request body"
}
```
```json 404 Not Found theme={null}
{
"error": "Settings not found"
}
```
```json 409 Conflict theme={null}
{
"error": "File modified externally",
"currentMtime": 1704467450000
}
```
```json 500 Server Error theme={null}
{
"error": "Failed to write settings file",
"message": "Detailed error message"
}
```
## Shared Data Endpoints
Available since v7.48.0
### GET /api/shared/commands
List all shared commands with descriptions.
### GET /api/shared/skills
List all shared skills with descriptions.
### GET /api/shared/agents
List all shared agents with descriptions.
### GET /api/shared/content
Load full markdown content for a shared item.
**Query Parameters:**
* `type`: `commands` | `skills` | `agents`
* `path`: Item path
### GET /api/shared/summary
Get counts and symlink status for all shared data types.
```json theme={null}
{
"commands": 5,
"skills": 3,
"agents": 2,
"total": 10,
"symlinkStatus": "ok"
}
```
## Droid Endpoints
Available since v7.48.0
### GET /api/droid/diagnostics
Get Factory Droid binary detection and configuration status.
### GET /api/droid/settings
Read `~/.factory/settings.json` with diagnostics.
### PUT /api/droid/settings
Write to `~/.factory/settings.json` with atomic write and mtime conflict detection.
**Request Body:**
* `content`: JSON string of settings
* `expectedMtime` (optional): Optimistic locking timestamp
## Config Endpoints
Available since v7.49.0
### GET /api/config
Get current CCS config.yaml as JSON.
### PUT /api/config
Update config.yaml with validation and conflict detection.
## Security Features
* **API Key Masking**: Automatic masking for display endpoints
* **Optimistic Locking**: `mtime`-based conflict detection prevents data loss
* **Atomic Writes**: Temp file + rename ensures crash safety
* **Automatic Backups**: Previous settings saved before updates
* **No Cache Headers**: Sensitive endpoints (`/raw`, `/auth/tokens/raw`) prevent caching
* **Localhost Only**: API only accessible on 127.0.0.1
# Usage Analytics API
Source: https://docs.ccs.kaitran.ca/reference/api-usage
REST API endpoints for Claude Code usage tracking and analytics
# Usage Analytics API
Track token usage, costs, and usage patterns across all Claude Code sessions. The usage analytics system aggregates data from JSONL files and provides multiple views of consumption data.
## Overview
The usage API provides endpoints for:
* Daily, hourly, and monthly usage summaries
* Per-model cost breakdowns
* Session history and project tracking
* Anomaly detection for cost spikes
* Real-time cache status
## Authentication
All endpoints are available on localhost only ([http://localhost:3000](http://localhost:3000)). No authentication required.
## Endpoints
### GET /api/usage/summary
Get overall usage summary with total tokens, cost, and daily averages.
**Query Parameters:**
* `since` (optional): Start date in YYYYMMDD format
* `until` (optional): End date in YYYYMMDD format
```bash Request theme={null}
curl "http://localhost:3000/api/usage/summary?since=20260101&until=20260131"
```
```json Response theme={null}
{
"totalTokens": 15000000,
"totalCost": 45.50,
"inputTokens": 10000000,
"outputTokens": 5000000,
"cacheReadTokens": 2000000,
"cacheWriteTokens": 500000,
"dailyAverage": {
"tokens": 500000,
"cost": 1.52
},
"dateRange": {
"from": "2026-01-01",
"to": "2026-01-31"
},
"modelsUsed": ["claude-sonnet-4", "gemini-3-flash"]
}
```
***
### GET /api/usage/daily
Get daily usage trends with per-day breakdowns.
```bash Request theme={null}
curl http://localhost:3000/api/usage/daily
```
```json Response theme={null}
{
"daily": [
{
"date": "2026-01-05",
"inputTokens": 450000,
"outputTokens": 200000,
"cacheReadTokens": 100000,
"cacheWriteTokens": 25000,
"cost": 1.85,
"modelsUsed": ["claude-sonnet-4", "gemini-3-flash"],
"modelBreakdown": {
"claude-sonnet-4": {
"inputTokens": 300000,
"outputTokens": 150000,
"cost": 1.35
},
"gemini-3-flash": {
"inputTokens": 150000,
"outputTokens": 50000,
"cost": 0.50
}
}
}
]
}
```
***
### GET /api/usage/hourly
Get hourly usage trends for detailed time-series analysis. Includes gap filling for continuous charts.
```bash Request theme={null}
curl http://localhost:3000/api/usage/hourly
```
```json Response theme={null}
{
"hourly": [
{
"hour": "2026-01-05 14:00",
"inputTokens": 50000,
"outputTokens": 20000,
"cacheReadTokens": 10000,
"cacheWriteTokens": 2500,
"cost": 0.21,
"modelsUsed": ["claude-sonnet-4"]
},
{
"hour": "2026-01-05 15:00",
"inputTokens": 0,
"outputTokens": 0,
"cost": 0,
"modelsUsed": []
}
]
}
```
***
### GET /api/usage/models
Get per-model usage statistics with cost breakdowns and I/O ratios.
```bash Request theme={null}
curl http://localhost:3000/api/usage/models
```
```json Response theme={null}
{
"models": [
{
"model": "claude-sonnet-4",
"inputTokens": 8000000,
"outputTokens": 3500000,
"cacheReadTokens": 1500000,
"cacheWriteTokens": 400000,
"cost": 32.50,
"percentage": 71.4,
"ioRatio": 2.29
},
{
"model": "gemini-3-flash",
"inputTokens": 2000000,
"outputTokens": 1500000,
"cost": 13.00,
"percentage": 28.6,
"ioRatio": 1.33
}
],
"totalCost": 45.50
}
```
***
### GET /api/usage/insights
Get usage anomalies and insights for cost optimization.
```bash Request theme={null}
curl http://localhost:3000/api/usage/insights
```
```json Response theme={null}
{
"anomalies": [
{
"type": "cost_spike",
"date": "2026-01-04",
"value": 5.20,
"threshold": 2.50,
"message": "Daily cost 208% above average"
},
{
"type": "high_input",
"date": "2026-01-03",
"value": 12000000,
"threshold": 10000000,
"message": "Input tokens exceeded 10M threshold"
}
],
"thresholds": {
"highInput": 10000000,
"highIoRatio": 100,
"costSpikeMultiplier": 2,
"highCacheRead": 1000000000
}
}
```
**Anomaly Types:**
* `cost_spike`: Daily cost significantly above average
* `high_input`: Input tokens exceed 10M threshold
* `high_io_ratio`: Input-to-output ratio exceeds 100:1
* `high_cache_read`: Cache read tokens exceed 1B
***
### GET /api/usage/sessions
Get session history with pagination support.
**Query Parameters:**
* `limit` (optional): Number of sessions to return (default: 50)
* `offset` (optional): Pagination offset (default: 0)
```bash Request theme={null}
curl "http://localhost:3000/api/usage/sessions?limit=10&offset=0"
```
```json Response theme={null}
{
"sessions": [
{
"sessionId": "abc123",
"projectPath": "~/projects/my-app",
"lastActivity": "2026-01-05T14:30:00Z",
"inputTokens": 100000,
"outputTokens": 50000,
"cost": 0.45,
"modelsUsed": ["claude-sonnet-4"],
"version": "1.2.3"
}
],
"total": 150,
"limit": 10,
"offset": 0
}
```
***
### GET /api/usage/monthly
Get monthly aggregated usage data.
```bash Request theme={null}
curl http://localhost:3000/api/usage/monthly
```
```json Response theme={null}
{
"monthly": [
{
"month": "2026-01",
"inputTokens": 10000000,
"outputTokens": 5000000,
"cacheReadTokens": 2000000,
"cacheWriteTokens": 500000,
"cost": 45.50
},
{
"month": "2025-12",
"inputTokens": 8000000,
"outputTokens": 4000000,
"cost": 36.00
}
]
}
```
***
### POST /api/usage/refresh
Force cache refresh to fetch latest usage data.
```bash Request theme={null}
curl -X POST http://localhost:3000/api/usage/refresh
```
```json Response theme={null}
{
"success": true,
"message": "Cache cleared, refreshing data",
"timestamp": 1704467400000
}
```
***
### GET /api/usage/status
Get cache status and last fetch timestamp.
```bash Request theme={null}
curl http://localhost:3000/api/usage/status
```
```json Response theme={null}
{
"cached": true,
"lastFetch": 1704467400000,
"lastFetchHuman": "2026-01-05T14:30:00Z",
"cacheAge": 120000,
"cacheAgeHuman": "2 minutes ago"
}
```
## Caching Strategy
The usage API uses a three-tier caching system:
1. **In-Memory Cache**: TTL varies by endpoint (1-5 minutes)
2. **Disk Cache**: Persisted to `~/.ccs/.cache/usage-cache.json` (7-day stale TTL)
3. **Stale-While-Revalidate**: Returns stale cache immediately, refreshes in background
### Cache Behavior
* **Fresh Cache** (\<1 min): Instant response from memory
* **Stale Cache** (1-7 days): Instant response, background refresh
* **No Cache**: Blocking fetch from JSONL files
## Data Sources
Usage data is aggregated from:
* `~/.claude/projects/*/usage.jsonl` - Default Claude directory
* `~/.ccs/instances/*/usage.jsonl` - CCS account instances
## Model Pricing
Costs are calculated using built-in pricing for:
* Claude (Haiku, Sonnet, Opus variants)
* OpenAI (GPT-4o, o1, o3, Codex)
* Google Gemini (Flash, Pro)
* GLM, Kimi, MiniMax, DeepSeek, Mistral
Pricing includes input/output tokens, cache creation, and cache reads.
## Error Responses
```json 500 Server Error theme={null}
{
"error": "Failed to fetch usage data",
"message": "Detailed error message"
}
```
```json 503 Service Unavailable theme={null}
{
"error": "Cache unavailable",
"message": "No cached data available and fetch failed"
}
```
# Architecture
Source: https://docs.ccs.kaitran.ca/reference/architecture
CCS system architecture and design
# Architecture
CCS is designed with simplicity and reliability in mind. The architecture follows YAGNI, KISS, and DRY principles.
## Core Components
Isolated Claude instances with separate credentials and session data
CLIProxy-based providers (Gemini, Codex, Agy) with zero config
Settings-based profiles for GLM, KM, and custom providers
Smart profile detection that checks CLIProxy → Settings → Account profiles in
order
Spawns Claude CLI with resolved profile settings via `--settings` flag
## Profile Mechanisms (Priority Order)
1. **CLIProxy hardcoded**: gemini, codex, agy → OAuth-based, zero config
2. **CLIProxy variants**: `config.cliproxy` section → user-defined providers
3. **Settings-based**: `config.profiles` section → GLM, KM
4. **Account-based**: Account metadata in `config.yaml` → isolated instances via `CLAUDE_CONFIG_DIR`
## Execution Flow
Smart detection of profile vs CLI flags
Check CLIProxy → Settings → Account profiles
Set env vars, CLAUDE\_CONFIG\_DIR if needed
Execute `claude --settings [args]`
## Directory Structure
```
~/.ccs/
├── config.yaml # Main configuration (v12 unified format)
├── glm.settings.json # GLM settings file
├── km.settings.json # Kimi for Coding settings file
│
├── instances/ # Account profile instances
│ ├── work/
│ │ ├── .credentials.json
│ │ ├── session-env/
│ │ └── ...
│ └── personal/
│
├── cliproxy/ # OAuth provider data
│ ├── auth/
│ │ ├── user@email-projectid.json # gemini tokens
│ │ ├── codex-user@email.json # codex tokens
│ │ └── antigravity-user_email.json # antigravity tokens
│ ├── bin/
│ │ ├── original/ # CLIProxyAPI binary
│ │ └── plus/ # CLIProxyAPIPlus binary
│ ├── config.yaml # CLIProxy configuration
│ ├── sessions.json # Active session tracking
│ └── accounts.json # Provider account registry
│
├── docker/ # Docker deployment assets (auto-generated)
│
├── shared/ # Symlinked across profiles
│ ├── commands/
│ ├── skills/
│ └── agents/
│
└── logs/ # CCS-owned structured logs
~/.claude/
├── settings.json # Claude Code settings
└── channels/
├── telegram/.env # TELEGRAM_BOT_TOKEN
└── discord/.env # DISCORD_BOT_TOKEN
```
## Design Principles
### Non-Invasive
* Never modifies `~/.claude/settings.json`
* Uses `--settings` flag for delegation
* Claude CLI manages its own state
### Idempotent
* All install operations safe to run multiple times
* Profile creation handles existing directories
* No side effects on repeated runs
### Cross-Platform Parity
* Same behavior on macOS, Linux, Windows
* Node.js handles platform differences
* Unified codebase for all platforms
### Configuration Priority Resolution
CCS resolves configuration in this order (highest to lowest priority):
1. **CLI flags** - Direct command-line arguments (`--proxy-host`, `--model`, etc.)
2. **Environment variables** - Shell exports (`CCS_PROXY_HOST`, `ANTHROPIC_MODEL`, etc.)
3. **config.yaml** - User configuration file (`~/.ccs/config.yaml`)
4. **Built-in defaults** - Hardcoded fallback values
This allows flexible overrides without modifying config files.
### Automatic Token Refresh
CLIProxy-backed OAuth providers rely on upstream/runtime-managed token refresh
where supported. CCS verifies local auth material and lets CLIProxy own the
actual refresh flow. This keeps long-running conversations from failing while
avoiding provider-specific refresh logic inside CCS itself.
**How it works:**
* CLIProxy-managed providers refresh upstream when their backend supports it
* CCS checks whether local auth material is still present and usable
* users normally do not need to refresh tokens manually during healthy sessions
* unsupported providers still fall back to re-auth when refresh is not available
### Graceful Degradation
CCS implements fallback mechanisms for robust operation:
**Remote → Local Proxy Fallback:**
* Attempts remote CLIProxy connection first
* On failure, automatically falls back to local proxy
* Configurable via `CCS_PROXY_FALLBACK_ENABLED` or `--remote-only` flag
* Health checks run with configurable timeout
**Network Resilience:**
* Handles connection timeouts gracefully
* Auto-retry on transient failures
* Clear error messages when fallback exhausted
## Technology Stack
| Component | Technology |
| --------- | -------------------- |
| CLI | Node.js (ES modules) |
| Build | Bun + TypeScript |
| Dashboard | React + Vite |
| Package | npm |
## Advanced Architecture Patterns
### Unified Config Pattern
CCS v6+ uses a single `config.yaml` file for all configuration instead of scattered JSON files. This simplifies management and enables atomic updates.
**Benefits:**
* Single source of truth for all settings
* Easier backup and version control
* Atomic configuration updates
* Reduced file I/O operations
**Migration:** Run `ccs migrate` to convert legacy config files to unified format.
### Session Reference Counting
CLIProxy tracks active sessions using reference counting to prevent premature shutdown:
* Each active Claude session increments counter
* Session end decrements counter
* Proxy only stops when counter reaches zero
* Prevents disruption of concurrent sessions
**Session Files:**
* `~/.ccs/cliproxy/sessions.json` - Global session tracking
* `~/.ccs/cliproxy/sessions-{port}.json` - Variant-specific sessions
### Version Mismatch Detection
CCS automatically detects CLIProxy binary version mismatches and handles them gracefully:
**Detection:**
* Compares expected version in config vs installed binary
* Checks on every proxy startup
* Validates on health check failures
**Auto-Restart:**
* Stops outdated proxy instance
* Downloads latest compatible version
* Restarts proxy with new binary
* Preserves session state
**User Impact:**
* Transparent to user (no interruption)
* Logged for debugging (`~/.ccs/logs/`)
* Optional notification in dashboard
## Docker Deployment Architecture
`ccs docker up` bundles CCS and CLIProxy into a Docker stack for team or server deployments.
```
Local Machine Remote Server
┌─────────────────┐ ┌────────────────────────────┐
│ │ SSH deploy │ Docker Stack │
│ ccs docker up │─────────────▶│ │
│ --host │ │ ┌──────────┐ ┌────────┐ │
│ │ │ │ CCS │ │Superv. │ │
└─────────────────┘ │ │ (daemon) │ │ (proc) │ │
│ └────┬─────┘ └────────┘ │
│ │ │
│ ┌────▼─────────────┐ │
│ │ CLIProxyAPI │ │
│ │ (port 8317) │ │
│ └────┬─────────────┘ │
└───────┼────────────────────-┘
│
▼
┌─────────────────┐
│ AI Providers │
│ (Gemini, etc.) │
└─────────────────┘
```
**Commands:**
| Command | Description |
| ---------------------------------- | --------------------------------------------- |
| `ccs docker up` | Build + start stack locally |
| `ccs docker up --host ` | Deploy to remote server |
| `ccs docker down` | Stop and remove stack |
| `ccs docker status` | Show compose + supervisor status |
| `ccs docker logs [--follow]` | Tail combined logs |
| `ccs docker update [--host]` | Update binaries in running container |
| `ccs docker config` | Show bundled paths + defaults |
| `ccs docker show-key [--full]` | Show the active Docker CLIProxy API key |
| `ccs docker finalize-key-rotation` | End the temporary legacy API key grace window |
***
## Multi-Target Runtime Routing
The `--target` flag (or argv0 aliases like `ccsd`, `ccsx`) routes profile execution to alternative CLI runtimes.
```
ccs glm --target droid / ccsx codex
│
▼
Profile resolution (same as normal)
│
▼
Target selection
├── target=claude → exec: claude --settings
├── target=droid → exec: @factory/cli --settings
│ │
│ ▼
│ CCS_DROID_PATH or PATH lookup
└── target=codex → exec: codex -c
│
▼
CCS_CODEX_API_KEY injected via env
(no file writes to ~/.codex/config.toml)
```
**Priority order for target:**
1. `--target` CLI flag (highest)
2. argv0 match (`ccsd` -> droid, `ccsx`/`ccs-codex` -> codex)
3. Profile `target` config key (`claude`, `droid`, or `codex`)
4. Default: `claude`
***
## Performance
| Operation | Time |
| ------------------------ | --------- |
| Profile switch | \< 10ms |
| First account activation | \~20-35ms |
| Subsequent activation | \~5-10ms |
| Dashboard startup | \~300ms |
# CLI Commands
Source: https://docs.ccs.kaitran.ca/reference/cli-commands
Complete reference for CCS commands
# CLI Commands
Complete reference for all CCS commands and options.
## Basic Usage
```bash theme={null}
ccs [profile] [args...]
```
* `profile` - Optional profile name (default: "default")
* `args` - Passed directly to Claude CLI
## Profile Commands
### Switch Profiles
```bash theme={null}
ccs # Use default Claude
ccs glm # Use GLM profile
ccs kimi # Use Kimi OAuth (CLIProxy)
ccs km # Use Kimi API key (Kimi for Coding direct)
ccs work # Use work account
ccs codex # Use Codex via OAuth
```
`ccs glmt` is deprecated and kept only for compatibility with existing legacy
scripts or configs. Use `ccs glm` for Z.AI API profiles and `ccs km` for
reasoning-first Kimi API profiles.
### With Arguments
```bash theme={null}
ccs glm --verbose
ccs /plan "add feature"
ccs glm /code "implement feature"
```
## Account Management
### Create Account Profile
```bash theme={null}
ccs auth create [--bare] [--force] [--share-context] [--context-group ] [--deeper-continuity]
```
Creates a new account profile and opens OAuth login.
For two isolated Claude accounts, create both profiles and run the one you want
explicitly:
```bash theme={null}
ccs auth create work
ccs auth create personal
ccs work "review code"
ccs personal "write tests"
```
Account credentials and tokens stay isolated per profile. Non-bare profiles
share `settings.json` and user `CLAUDE.md` from `~/.claude/`; history sharing
is separate and only happens when accounts use shared mode and the same
context group.
#### Bare Profiles
```bash theme={null}
ccs auth create sandbox --bare
```
The `--bare` flag creates a clean profile **without shared symlinks** (commands, skills, agents, `settings.json`, or `CLAUDE.md`). Bare profiles are useful for sandboxed or testing environments where you want a minimal Claude instance with no inherited configuration.
**Bare vs non-bare behavior:**
| Aspect | Non-bare (default) | Bare (`--bare`) |
| ----------------------------- | ----------------------------------- | --------------------- |
| Shared commands/skills/agents | Symlinked from `~/.ccs/shared/` | Not linked |
| Shared settings/instructions | Linked from `~/.ccs/shared/` | Not linked |
| MCP server sync | Synced from global `~/.claude.json` | Skipped |
| `ccs sync` | Updates MCP servers | Skipped |
| OAuth credentials | Isolated per instance | Isolated per instance |
Once created with `--bare`, the flag persists across profile updates and `ccs sync` runs.
### List Profiles
```bash theme={null}
ccs auth list
```
Shows all configured profiles with their status.
### Show Profile
```bash theme={null}
ccs auth show
ccs auth show --json
```
Shows credential isolation, account context mode, `settings.json` sync state,
local history summary, and whether plain `ccs` currently resumes from the same
lane.
### Set Default
```bash theme={null}
ccs auth default
```
Sets the default profile for plain `ccs` launches. Back up the current native
lane first if you might need old `~/.claude/projects` history:
```bash theme={null}
ccs auth backup default
ccs auth default work
```
Changing the default aligns future plain `ccs` runs with that account profile.
It does not import old native history into the selected profile.
### Reset Default
```bash theme={null}
ccs auth reset-default
```
Restores the original CCS default profile.
### Remove Profile
```bash theme={null}
ccs auth remove --force
```
Removes profile and deletes instance directory.
### Shared Resources
```bash theme={null}
ccs auth resources
ccs auth resources --mode shared|profile-local
ccs auth resources --json
```
Inspect or change whether a profile shares plugins, settings, `CLAUDE.md`,
commands, skills, and agents from `~/.claude/`, or keeps them profile-local.
* `--mode shared` links shared resources into the profile instance (default
for most profiles).
* `--mode profile-local` (equivalent to `ccs auth create --bare`) isolates the
profile from `~/.claude/` so the instance carries its own resource set.
* Without `--mode`, prints the current mode and effective behavior.
* `--json` emits machine-readable output for scripts.
## API Profile Management
Manage custom API key-based profiles:
### Basic Operations
```bash theme={null}
# Create new API profile
ccs api create [name] [--preset ] [--base-url ] [--target claude|droid|codex]
# List all API profiles
ccs api list
# Remove an API profile
ccs api remove
```
### Profile Lifecycle (Discover, Copy, Export, Import)
Available since v7.52.0
```bash theme={null}
# Discover orphaned .settings.json files
ccs api discover
# Discover and register orphaned profiles
ccs api discover --register
# Copy existing profile to new name
ccs api copy
# Export profile to portable JSON file
ccs api export --out
# Export with API key included
ccs api export --out --include-secrets
# Import profile from JSON file
ccs api import
# Import to specific profile name
ccs api import --name
```
### Using API Profiles
```bash theme={null}
# Run with API profile
ccs glm "your prompt"
ccs km "analyze this"
ccs llamacpp "local task"
ccs anthropic "direct API"
# Configure specific profile
ccs config
# Navigate to API Profiles tab
```
## OAuth Provider Commands
Built-in CLIProxy provider shortcuts now include:
`agy` · `claude` · `codex` · `xai` · `gemini` · `qwen` · `iflow` · `kimi` · `kiro` · `cursor` · `gitlab` · `codebuddy` · `kilo` · `qoder`
Deprecated compatibility shortcut: `ghcp`
`grok` is an alias for `xai`; both commands share accounts, settings, model
catalog, and routing.
Qwen account linking is currently unavailable in the bundled CLIProxy runtime.
Use an API-key Qwen profile such as Alibaba Coding Plan instead.
### Basic Usage
```bash theme={null}
ccs codex "your prompt"
ccs xai "your prompt" # ccs grok is equivalent
ccs kimi "your prompt"
ccs iflow "your prompt"
ccs cursor "your prompt"
ccs gitlab "your prompt"
ccs qoder "your prompt"
ccs "your prompt"
```
### Authentication
```bash theme={null}
ccs codex --auth # Auth only, no session
ccs codex --auth --add # Add another account
```
### Multi-Account
```bash theme={null}
ccs codex --accounts # List all accounts
ccs codex --use # Switch to account
```
### Model Configuration
```bash theme={null}
ccs codex --config # Change model (interactive)
ccs kimi --config # Change model (interactive)
ccs xai --config # Change model (interactive)
```
### GitLab Duo Auth Variants
```bash theme={null}
# Browser OAuth
ccs gitlab --auth
# PAT login instead of browser OAuth
ccs gitlab --auth --gitlab-token-login
# Self-hosted GitLab
ccs gitlab --auth --gitlab-url https://gitlab.example.com
```
### Multi-Account Management
```bash theme={null}
# List all accounts for a provider
ccs codex --accounts
# Switch to a specific account
ccs codex --use
# Add another account (requires --auth)
ccs codex --auth --add
# Set account nickname
ccs codex --nickname
```
### Logout
```bash theme={null}
ccs codex --logout # Clear cached tokens
ccs kiro --logout
```
### Headless Mode
```bash theme={null}
ccs codex --headless # No browser, get URL for remote auth
```
### Kiro-Specific Options
```bash theme={null}
# Import token from Kiro IDE
ccs kiro --import
# Auth method selection
ccs kiro --auth --kiro-auth-method aws
ccs kiro --auth --kiro-auth-method aws-authcode --paste-callback
ccs kiro --auth --kiro-auth-method google
ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start
# Use normal browser (saves AWS login)
ccs kiro --no-incognito
```
### Codex Reasoning Effort
```bash theme={null}
# Override reasoning effort
ccs codex --effort medium # Standard reasoning
ccs codex --effort high # Deep reasoning
ccs codex --effort xhigh # Maximum, capped by model support
ccs codex --thinking xhigh # Alias for --effort
```
`gpt-5.4-mini` caps at `high`. `gpt-5.2`, `gpt-5.3-codex`, `gpt-5.3-codex-spark`, `gpt-5.4`, and `gpt-5.5` support `xhigh`.
For Codex GPT models that expose the fast service tier, append `-fast` to the
model ID. Combine it with effort suffixes when you want both controls:
```bash theme={null}
gpt-5.4-fast
gpt-5.4-high-fast
gpt-5.4-xhigh-fast
gpt-5.5-high-fast
```
CCS sends the canonical upstream model, for example `gpt-5.4`, with
`reasoning.effort` and `service_tier: "priority"` instead of forwarding the
suffixed string as a raw upstream model name.
## Cursor Provider And Legacy Bridge
The current `ccs cursor` shortcut is a **CLIProxy provider**. The older local
Cursor daemon workflow still exists only under `ccs legacy cursor`.
```bash theme={null}
# Current provider path
ccs cursor --auth
ccs cursor --accounts
ccs cursor --config
ccs cursor "your prompt"
# Deprecated compatibility path
ccs legacy cursor auth
ccs legacy cursor status
ccs legacy cursor start
ccs legacy cursor probe
```
Older `ccs cursor auth/status/start/...` subcommands are still shimmed for a
migration window, but they forward to the legacy bridge with a deprecation
warning.
## Droid Multi-Target Adapter
Route profiles to alternative CLI targets:
```bash theme={null}
# Explicit target flag
ccs glm --target droid
# Built-in ccsd shorthand (busybox argv0 pattern)
ccsd glm "your prompt" # Equivalent to: ccs glm --target droid
ccsd codex "your prompt" # OAuth-backed profile on Droid
ccsd km "prompt" # API profile on Droid
# Custom aliases via env var
export CCS_DROID_ALIASES=mydroid
mydroid glm "your prompt"
```
**Setup `ccsd`:**
```bash theme={null}
ln -s $(which ccs) /usr/local/bin/ccsd
```
See [Droid Adapter](/features/workflow/droid-adapter) for full documentation.
## Codex Runtime Target
Available since v7.62.0
Route profiles to the native Codex CLI:
```bash theme={null}
# Built-in aliases
ccs-codex "your prompt"
ccsx codex "implement auth flow"
# Codex-on-Codex power shortcut (native Codex + CLIProxy Codex pool)
ccsxp "your prompt"
# Explicit target flag
ccs codex --target codex "your prompt"
# Custom aliases
export CCS_TARGET_ALIASES='codex=mycodex'
# Legacy: export CCS_CODEX_ALIASES=mycodex
```
**Setup aliases:**
```bash theme={null}
ln -s $(which ccs) /usr/local/bin/ccsx
ln -s $(which ccs) /usr/local/bin/ccsxp
```
Most Codex target credentials are delivered via transient `-c` overrides and `CCS_CODEX_API_KEY` env var. `ccsxp` also repairs the native Codex `[model_providers.cliproxy]` entry when needed and injects the managed token into that provider's `env_key`; no API key is written to disk.
See [Codex Adapter](/features/workflow/codex-adapter) for full documentation.
## CLIProxy Management
Manage the CLIProxyAPI binary:
```bash theme={null}
# Show status and version
ccs cliproxy
# Show full help
ccs cliproxy --help
# Install specific version
ccs cliproxy --install
# e.g., ccs cliproxy --install 6.5.53
# Update to latest version
ccs cliproxy --latest
```
### Lifecycle Commands
```bash theme={null}
# Start CLIProxy
ccs cliproxy start
# Restart CLIProxy
ccs cliproxy restart
# Stop CLIProxy
ccs cliproxy stop
# Show status (PID, port, sessions)
ccs cliproxy status
```
### Variant Management
```bash theme={null}
# Create single-provider variant
ccs cliproxy create [name]
# Create composite variant (mix providers per tier)
ccs cliproxy create --composite
# Edit existing variant
ccs cliproxy edit [name]
# Remove variant
ccs cliproxy remove
# List all variants
ccs cliproxy list
```
Codex variants can pin both effort and fast mode through the model value:
```bash theme={null}
ccs cliproxy create codex-fast --provider codex --model gpt-5.4-high-fast
```
Dashboard parity:
* `ccs config` -> `CLIProxy`
* Create or edit a Codex variant
* Pick `gpt-5.4-fast`, `gpt-5.4-high-fast`, or `gpt-5.4-xhigh-fast` in the model selector
### Quota Management
Manage account quota and rotation:
```bash theme={null}
# Show quota, tier, and pause status for all providers
ccs cliproxy status
# Show status for specific provider
ccs cliproxy status agy
ccs cliproxy status claude # Claude OAuth quota
ccs cliproxy status ghcp # Deprecated GitHub Copilot compatibility quota
# Show quota summary across all supported providers
ccs cliproxy quota
```
`ccs cliproxy quota` displays quota sections for supported providers such as
`agy`, `codex`, `gemini`, and `claude`. `ghcp` may appear for existing
deprecated Copilot compatibility setups.
When automatic quota management is enabled, CCS checks the full active account
pool before local CLIProxy startup. Known-exhausted accounts are temporarily
paused out of rotation when another healthy account exists, then automatically
resume after the cooldown window.
```bash theme={null}
# Pause an account from rotation
ccs cliproxy pause
# e.g., ccs cliproxy pause agy user@gmail.com
# Resume a paused account
ccs cliproxy resume
# e.g., ccs cliproxy resume agy user@gmail.com
```
### Routing Strategy
Inspect and change the proxy-wide routing strategy explicitly:
```bash theme={null}
# Show current strategy and source
ccs cliproxy routing
# Explain the tradeoff
ccs cliproxy routing explain
# Change strategy
ccs cliproxy routing set fill-first
ccs cliproxy routing set round-robin
```
**Available strategies:**
* `round-robin` - spread requests across matching healthy accounts
* `fill-first` - drain one healthy account before moving to backups
CCS keeps `round-robin` as the default until you explicitly change it.
### Pool Routing
Turn several Claude accounts into a pool that auto-continues when one account
hits its limit. See [Account Pools](/features/pool) for the full guide.
```bash theme={null}
# Show pool routing status
ccs cliproxy pool
# Enable pool routing (fill-first + session affinity + cooling on + retry cap)
ccs cliproxy pool --enable
# Disable pool routing and restore a safe non-pool config
ccs cliproxy pool --disable
```
Use `ccs cliproxy pool --disable` to leave a pool. Do not hand-edit routing
back to plain round-robin with no affinity on a multi-account fleet; that
state re-processes your whole conversation on most turns. See [Leaving a
pool](/features/pool#leaving-a-pool).
### Account Drain Order
Control the order accounts are drained in within a provider:
```bash theme={null}
# Show the effective drain order
ccs cliproxy accounts order
# Set a manual order (comma-separated account IDs)
ccs cliproxy accounts order --set a@x.com,b@y.com
# Derive order from tier metadata (ultra > pro > free); agy and gemini only
ccs cliproxy accounts order --by-tier
# Revert to stable file order
ccs cliproxy accounts order --reset
```
Tier-based ordering (`--by-tier`) is available for `agy` and `gemini`. Claude
accounts have unknown tier; use `--set` for a manual order.
### Model Catalog Sync
Available since v7.61.1
Sync remote model catalogs from CLIProxyAPI with static fallback catalogs:
```bash theme={null}
# View current catalog cache status
ccs cliproxy catalog
# Force refresh from remote
ccs cliproxy catalog refresh
# Reset to static catalog (clear cache)
ccs cliproxy catalog reset
```
**Syncable Providers:** `agy`, `claude`, `codex`, `gemini`, `iflow`, `kimi`,
`kiro`, `qoder`, `qwen`, `xai`, plus deprecated `ghcp` compatibility
**Cache Details:**
* Location: `~/.ccs/model-catalog-cache.json`
* TTL: 24 hours
* Merge strategy: Remote overrides static fields, static-only fields preserved
**CLIProxy Paths:**
| Path | Description |
| ----------------------------------- | ---------------- |
| `~/.ccs/cliproxy/bin/cli-proxy-api` | Binary location |
| `~/.ccs/cliproxy/config.yaml` | Configuration |
| `~/.ccs/cliproxy/auth/` | OAuth tokens |
| `~/.ccs/cliproxy/sessions.json` | Session tracking |
| `~/.ccs/cliproxy/accounts.json` | Account registry |
Default port: 8317
### Remote Proxy Configuration
Connect to a remote CLIProxy server:
```bash theme={null}
# Configure remote proxy via CLI flags
ccs --proxy-host --proxy-port --proxy-auth-token
# Set proxy protocol (http/https)
ccs --proxy-protocol https
# Set health check timeout
ccs --proxy-timeout
# Allow self-signed certificates
ccs --allow-self-signed
# Force local proxy mode
ccs --local-proxy
# Fail if remote unreachable (no fallback)
ccs --remote-only
```
### Local OpenAI-Compatible Proxy
Manage the local Anthropic-compatible proxy for API profiles that point at
OpenAI-compatible chat-completions endpoints:
```bash theme={null}
# Start a local proxy for one profile
ccs proxy start hf
# Export the runtime environment for Claude-compatible clients
eval "$(ccs proxy activate hf)"
ccs proxy activate --fish
# Inspect or stop a running profile proxy
ccs proxy status hf
ccs proxy stop hf
```
**Port behavior:**
* `--port` pins a one-off launch
* `proxy.profile_ports.` pins a saved profile port
* `proxy.port` guides the shared preferred starting port
* otherwise CCS chooses an adaptive per-profile fallback
See [OpenAI-Compatible Provider Routing](/features/proxy/openai-compatible-providers).
## Docker Deployment
Deploy CCS and CLIProxy as a Docker stack for team or server use.
```bash theme={null}
# Build and start stack locally
ccs docker up
# Deploy remotely via SSH
ccs docker up --host
# Stop and remove stack
ccs docker down
# Show compose + supervisor status
ccs docker status
# Tail combined logs
ccs docker logs
# Follow logs continuously
ccs docker logs --follow
# Update binaries in running container
ccs docker update
# Update binaries on remote container
ccs docker update --host
# Show bundled paths and defaults
ccs docker config
# Show the current Docker CLIProxy API key
ccs docker show-key
# Remove the temporary legacy API key after client updates
ccs docker finalize-key-rotation
```
**Examples:**
```bash theme={null}
# Deploy to remote server
ccs docker up --host user@myserver.com
# Follow logs after deploy
ccs docker logs --follow
# Update CLIProxy binary without restart
ccs docker update --host user@myserver.com
# Copy the active API key into a downstream client
ccs docker show-key --full
```
The `ccs docker` commands require Docker and Docker Compose on the target
host. Remote deployment uses the SSH target alias from `~/.ssh/config`.
Docker upgrades that replace the historical `ccs-internal-managed` API key
keep that legacy key valid beside the new per-install key for a temporary
grace window. The `ccs docker up` banner masks the new key; update clients
with `ccs docker show-key --full`, then run `ccs docker finalize-key-rotation`
when the old key is no longer needed. For already-broken upgrades, opt in
explicitly with `CCS_DOCKER_RESTORE_LEGACY_API_KEY=1`.
## Migration Commands
Migrate to unified configuration format:
```bash theme={null}
# Trigger manual migration
ccs migrate
# Show migration help
ccs migrate --help
```
Migrations run automatically on first launch after updates. Use `ccs migrate`
to manually trigger or re-run migrations.
## Utility Commands
### Version
```bash theme={null}
ccs --version
```
Shows CCS version and installation details:
```
CCS (Claude Codex Switch) v7.61.1
Installation:
Location: /home/user/.local/bin/ccs
Config: ~/.ccs/config.yaml
Documentation: https://docs.ccs.kaitran.ca
```
### Help
```bash theme={null}
ccs --help
```
Shows comprehensive usage documentation.
### Update
```bash theme={null}
ccs update # Standard update
ccs update --force # Force reinstall
ccs update --beta # Install beta channel
ccs update --force --beta # Force beta install
```
### Configuration Dashboard
```bash theme={null}
ccs config
ccs config --port 3000 # Use specific port
ccs config --host localhost # Default local-only binding
ccs config --host 0.0.0.0 # Reachable from another device
```
Opens the visual configuration dashboard in your browser using the effective bind/port.
By default CCS binds the dashboard to `localhost`. When the effective bind is reachable beyond loopback, CCS prints network URLs plus an auth reminder.
If auth is disabled, remote users can still view read-only dashboard surfaces,
but sensitive write routes stay localhost-only.
### CCS Bar
```bash theme={null}
ccs bar # Launch on the saved or first available port
ccs bar --port 3999 # Launch on, or safely move to, an exact port
ccs bar status # Check the process record and HTTP reachability
ccs bar stop # Safely stop the verified background process
```
`--port` requires an available integer from `1` to `65535`. The selected port
persists in the launch descriptor, so later launches try it first even after
`ccs bar stop`. When moving a live server, CCS preflights the new port and
restores the prior server if the replacement fails; failed restoration
preserves the previous discovery and launch state for recovery.
`status` distinguishes a stopped server, an invalid or stale process record, a
live process with a failed HTTP probe, and a reachable server. `stop` signals a
process only when its PID and recorded start identity still match. It removes
`server.pid` and `bar.json` after a confirmed stop or stale process, but keeps
them on identity mismatch, permission failure, signal failure, or timeout.
Legacy PID-only `server.pid` files cannot prove process identity. Current CCS
reports them as invalid and refuses to signal or clean them up. Confirm the CCS
server process in Activity Monitor, or restart macOS, before moving the stale
files aside; never signal the recorded number without verifying the process.
See [CCS Bar](/features/dashboard/ccs-bar) for installation, lifecycle details,
and troubleshooting.
### Dashboard Authentication CLI
Configure optional login protection for the dashboard:
```bash theme={null}
# Interactive setup wizard
ccs config auth setup
# Show current auth configuration
ccs config auth show
# Disable authentication
ccs config auth disable
```
**Setup Wizard Prompts:**
* Username (alphanumeric + underscore, 3-50 chars)
* Password (min 8 chars, prompted twice)
* Writes bcrypt hash to config.yaml
Environment variables `CCS_DASHBOARD_AUTH_ENABLED`, `CCS_DASHBOARD_USERNAME`,
and `CCS_DASHBOARD_PASSWORD_HASH` override config.yaml values. A warning is
shown during setup if ENV vars are detected.
If you expose the dashboard beyond localhost, protect it first with `ccs
config auth setup`.
### Claude IDE Extension Setup
Generate setup for the Anthropic Claude extension in VS Code-compatible hosts:
```bash theme={null}
# Preferred shared-settings path
ccs persist glm
ccs persist work
ccs persist default
# IDE-local settings.json snippets
ccs env glm --format claude-extension --ide vscode
ccs env work --format claude-extension --ide cursor
ccs env default --format claude-extension --ide windsurf
```
**Host-specific output:**
* `vscode`, `cursor` → `claudeCode.environmentVariables` plus `claudeCode.disableLoginPrompt`
* `windsurf` → `claude-code.environmentVariables`
Dashboard parity:
* `ccs config` → `Claude Extension`
* Copy the shared `~/.claude/settings.json` payload or an IDE-local JSON snippet
### Thinking Configuration
Configure extended thinking/reasoning budget settings:
```bash theme={null}
# Show current thinking config
ccs config thinking
# Set mode
ccs config thinking --mode auto # Tier-based defaults
ccs config thinking --mode off # Disable thinking
ccs config thinking --mode manual # Use override value
# Persistent override
ccs config thinking --override high
ccs config thinking --override max
ccs config thinking --override 24576
ccs config thinking --clear-override
# Per-tier defaults
ccs config thinking --tier opus high
ccs config thinking --tier sonnet medium
ccs config thinking --tier haiku low
# Per-provider overrides
ccs config thinking --provider-override gemini opus xhigh
ccs config thinking --provider-override claude opus max
ccs config thinking --provider-override agy sonnet high
ccs config thinking --clear-provider-override gemini
ccs config thinking --clear-provider-override gemini opus
```
See [Extended Thinking](/features/ai/extended-thinking) for full documentation.
### Droid Runtime Target
Configure the default CLI target for Droid profiles:
```bash theme={null}
# Route a profile to Droid at runtime
ccs glm --target droid
# Or use the ccsd shorthand
ccsd glm "your prompt"
# Set per-profile target in config
# config.yaml: profiles.my-profile.target: droid
```
**Target values:**
| Target | Description |
| -------- | -------------------------------------- |
| `claude` | Default — use Claude Code CLI |
| `droid` | Use Factory Droid CLI (`@factory/cli`) |
The `--target` flag overrides the profile's configured target and `ccsd` argv0
detection. See [Droid Adapter](/features/workflow/droid-adapter) for setup.
### Official Channels Configuration
Configure Anthropic's official Claude channels auto-enable for compatible Claude sessions:
```bash theme={null}
# Show current Official Channels status
ccs config channels
# Select which official channels CCS should auto-enable
ccs config channels --set telegram,discord
ccs config channels --set all
ccs config channels --clear
# Optional unattended mode
ccs config channels --unattended
ccs config channels --no-unattended
# Save or clear per-channel bot tokens
ccs config channels --set-token telegram=
ccs config channels --set-token discord=
ccs config channels --clear-token telegram
ccs config channels --clear-token
```
**Behavior:**
* Stores selected channels in `~/.ccs/config.yaml` under `channels`
* Stores `TELEGRAM_BOT_TOKEN` in `~/.claude/channels/telegram/.env`
* Stores `DISCORD_BOT_TOKEN` in `~/.claude/channels/discord/.env`
* Auto-adds `--channels` with any selected ready official plugins at runtime
* Supported official channels: Telegram, Discord, and iMessage
* Applies only to native Claude `default` and `account` sessions
* Never auto-enables for API-key profiles, CLIProxy, Copilot, or Droid targets
* `--unattended` maps to runtime `--dangerously-skip-permissions` only when auto-enable is active
* Explicit user `--channels` or permission flags win over CCS defaults
* iMessage is macOS-only and does not use a bot token
**Manual Claude-side setup:**
```bash theme={null}
/plugin install telegram@claude-plugins-official
/telegram:configure
/telegram:access pair
/telegram:access policy allowlist
/plugin install discord@claude-plugins-official
/discord:configure
/discord:access pair
/discord:access policy allowlist
/plugin install imessage@claude-plugins-official
/imessage:access allow +15551234567
```
### Image Analysis Configuration
Configure automatic image and PDF analysis for third-party launches:
```bash theme={null}
# Show current image analysis configuration
ccs config image-analysis
# Enable image analysis
ccs config image-analysis --enable
# Disable image analysis
ccs config image-analysis --disable
# Set analysis timeout in seconds
ccs config image-analysis --timeout 120
# Set vision model for a specific provider
ccs config image-analysis --set-model agy gemini-2.5-flash
ccs config image-analysis --set-model codex gpt-5.1-codex-mini
# Set the fallback backend for bridge-backed profiles
ccs config image-analysis --set-fallback agy
# Override backend for a specific settings profile
ccs config image-analysis --set-profile-backend glm agy
ccs config image-analysis --clear-profile-backend glm
```
**Default Behavior:**
* CCS uses a managed `ImageAnalysis` MCP tool when the runtime is healthy
* Healthy launches suppress the legacy CCS image `Read` hook
* CCS can fall back to compatibility hook behavior, then native `Read`, if the
managed runtime is not usable
* Supported formats: JPEG, PNG, GIF, WebP, HEIC, BMP, TIFF, PDF
**Use Cases:**
* Screenshots and architecture diagrams
* PDF documents and forms
* Technical images and diagrams
* Any visual content Claude needs to analyze
### Browser Automation
Configure Claude Browser Attach and Codex Browser Tools:
```bash theme={null}
# Setup and inspect browser automation
ccs help browser
ccs browser setup
ccs browser status
ccs browser doctor
# Control saved exposure policy
ccs browser policy
ccs browser policy --all manual
ccs browser enable claude
ccs browser disable codex
# Per-launch overrides
ccs glm --browser "inspect the app"
ccs glm --no-browser "summarize the docs"
ccs default --target codex --browser "use browser tools"
```
**Behavior:**
* New installs keep both lanes disabled and manual
* `ccs browser setup` is the primary remediation flow
* `ccs browser doctor` is read-only
* `--browser` opts in for one launch when the lane is enabled
* `--no-browser` suppresses tooling for one launch
See [Browser Automation](/features/workflow/browser-automation).
### Health Check
```bash theme={null}
ccs doctor # Run diagnostics
ccs doctor --fix # Auto-fix issues
ccs doctor -f # Short form
```
Checks configuration, symlinks, permissions, and provider status.
### Sync Shared Data
```bash theme={null}
ccs sync
```
Re-creates symlinks for shared commands, skills, and agents across profiles. Also syncs MCP servers from global `~/.claude.json` to all non-bare profile instances.
#### MCP Server Sync
During `ccs sync` (and on every profile launch), CCS copies the `mcpServers` key from global `~/.claude.json` into each instance's `.claude.json`.
**Merge behavior:**
* Global MCP servers are used as the base
* Instance-specific MCP server overrides are preserved (instance wins on conflict)
* Only the `mcpServers` key is copied -- OAuth sessions, caches, and other keys are **not** touched
**Exclusions:**
* Bare profiles (`--bare`) are skipped entirely
* Instances without a directory are skipped
MCP sync only copies server configuration. OAuth sessions and cached
credentials in `~/.claude.json` are never shared with instances.
### Cleanup
```bash theme={null}
ccs cleanup
```
Removes orphaned resources, old CLIProxy logs, and temporary files. Helps reclaim disk space and resolve stale session issues.
### Persist Command
Write the resolved Claude setup to `~/.claude/settings.json` for native Claude Code usage (IDE extensions, web-based Claude Code).
```bash theme={null}
# Persist a profile's resolved Claude setup to settings.json
ccs persist
# Skip confirmation prompts, auto-backup
ccs persist --yes
ccs persist -y
```
**Supported Profiles:**
* API profiles (glm, km, custom API profiles)
* CLIProxy profiles (gemini, codex, xai, agy, kiro, kimi, qoder, ghcp)
* Copilot profiles (requires copilot-api daemon running)
* Account profiles created with `ccs auth create`
* `default` profile
#### Backup Management
Before modifying settings.json, CCS creates timestamped backups:
```bash theme={null}
# List all available backups
ccs persist --list-backups
# Restore from latest backup
ccs persist --restore
# Restore from specific backup
ccs persist --restore 20260110_205324
```
**Backup Details:**
* Location: `~/.claude/settings.json.backup.YYYYMMDD_HHMMSS`
* Maximum: 10 backups (oldest auto-deleted)
* Permissions: 0o600 (owner read/write only)
#### Security Features
* **Symlink Rejection:** Rejects symlinked settings.json or backup files (prevents malicious writes)
* **JSON Validation:** Validates JSON integrity before restore
* **Masked Output:** API keys and tokens are masked in console output
* **Backup Prompt:** Default "yes" to backup before modification
#### Example Workflow
```bash theme={null}
# Step 1: Persist GLM profile
ccs persist glm
# → Creates backup
# → Writes resolved setup to settings.json
# → Shows masked output
# Step 2: Later, restore original settings
ccs persist --restore
# → Restores from latest backup
```
### Environment Export
Export environment variables for third-party tool integration (OpenCode, Cursor, Continue, etc.).
```bash theme={null}
ccs env [--format openai|anthropic|raw|claude-extension] [--shell auto|bash|zsh|fish|powershell] [--ide vscode|cursor|windsurf]
```
**Formats:**
| Format | Variables | Use Case |
| ------------------ | --------------------------------------------------------------------- | --------------------------------------------------------- |
| `openai` | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `LOCAL_ENDPOINT`, `OPENAI_MODEL` | OpenCode, Cursor, Continue |
| `anthropic` | `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL` | Claude-compatible tools |
| `claude-extension` | Host-specific `settings.json` snippet | Anthropic Claude extension in VS Code, Cursor, Windsurf |
| `raw` | All effective env vars | Debugging, custom scripts, inspecting `CLAUDE_CONFIG_DIR` |
**Shell Syntax:**
| Shell | Flag | Auto-detected |
| ---------- | --------------- | ------------------------------------------ |
| Bash/Zsh | `bash` or `zsh` | From `$SHELL` (default) |
| Fish | `fish` | From `$SHELL` containing `fish` |
| PowerShell | `powershell` | From `$SHELL` containing `pwsh` or Windows |
**Supported Profile Types:**
| Profile Type | Example | Supported |
| ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------- |
| CLIProxy (OAuth) | `gemini`, `codex`, `xai`, `agy`, `kiro`, `kimi`, `qoder`, `ghcp` | Yes |
| Settings (API) | `glm`, `km`, custom | Yes |
| Copilot | `copilot` | Yes |
| Account/default | `work`, `personal`, `default` | Yes (`claude-extension`; `raw` for `CLAUDE_CONFIG_DIR`) |
**Examples:**
```bash theme={null}
# OpenAI-compatible vars for OpenCode/Cursor
eval $(ccs env gemini --format openai)
# Anthropic vars for Claude-compatible tools
ccs env codex --format anthropic
# Fish shell syntax
eval (ccs env agy --format openai --shell fish)
# PowerShell
ccs env gemini --format openai --shell powershell | Invoke-Expression
# Settings-based profiles (glm, km)
eval $(ccs env glm --format raw)
```
The `--format` flag defaults to `anthropic`. The `--shell` flag defaults to
`auto` (detects from `$SHELL` environment variable). The `zsh` shell option
maps to `bash` syntax since they are compatible.
`--ide ` applies to `--format claude-extension` and accepts `vscode`, `cursor`, or `windsurf`.
For account and `default` profiles, `--format claude-extension` is the primary path. `--format raw` can expose `CLAUDE_CONFIG_DIR`, while `openai` and `anthropic` only produce transport vars for settings, CLIProxy, and Copilot profiles.
### Shell Completion
```bash theme={null}
ccs --shell-completion
ccs -sc
```
Installs shell auto-completion scripts for bash/zsh/fish.
### Token Management
```bash theme={null}
ccs tokens
```
Manage authentication tokens for OAuth providers. View, refresh, or revoke tokens across all accounts.
## Headless Delegation
Execute prompts without interactive session:
```bash theme={null}
ccs -p "your prompt"
ccs --prompt "your prompt"
ccs glm -p "implement feature"
```
Headless mode is useful for CI/CD pipelines, automation scripts, and remote
execution scenarios where interactive sessions aren't available.
## Copilot Commands (Deprecated)
Copilot-specific subcommands remain available for existing deprecated GitHub
Copilot compatibility setups:
```bash theme={null}
ccs copilot
```
GitHub usage-based Copilot billing begins June 1, 2026. Prefer Codex or
another active provider for new work.
### Copilot Usage Quota
```bash theme={null}
ccs copilot usage
```
Shows current GitHub Copilot quota consumption:
```
GitHub Copilot Usage
Premium interactions: 42 / 300
Chat: 128 / 500
Completions: 2341 / unlimited
Plan: individual
Quota resets: 2026-03-01
```
## Environment Variables
### Core Configuration
| Variable | Description |
| ---------------------- | ----------------------------------------------------- |
| `CCS_CONFIG` | Override config file path |
| `CCS_CLAUDE_PATH` | Override Claude CLI location |
| `NO_COLOR` | Disable colored output |
| `CCS_DEBUG` | Enable verbose debug logging |
| `CCS_DEBUG_LOG` | Enable debug logging (legacy) |
| `ANTHROPIC_AUTH_TOKEN` | API key for settings-based profiles |
| `ANTHROPIC_BASE_URL` | API base URL override |
| `ANTHROPIC_MODEL` | Model name override |
| `CLAUDE_CONFIG_DIR` | Claude config directory (used for instance isolation) |
### Remote Proxy Configuration
| Variable | Description |
| ---------------------------- | ---------------------------------------------- |
| `CCS_PROXY_HOST` | Remote proxy hostname |
| `CCS_PROXY_PORT` | Remote proxy port number |
| `CCS_PROXY_AUTH_TOKEN` | Remote proxy authentication token |
| `CCS_PROXY_PROTOCOL` | Proxy protocol (http/https) |
| `CCS_PROXY_TIMEOUT` | Remote proxy health check timeout (ms) |
| `CCS_PROXY_FALLBACK_ENABLED` | Enable fallback to local proxy if remote fails |
| `CCS_ALLOW_SELF_SIGNED` | Accept self-signed SSL certificates |
### Thinking
| Variable | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CCS_THINKING` | Per-session thinking override. Accepts: `minimal`, `low`, `medium`, `high`, `xhigh`, `auto`, `off`, `none`, `disabled`, `0`, or integer budget (0-100000) |
### Droid / Multi-Target
| Variable | Description |
| -------------------- | ---------------------------------------------------- |
| `CCS_DROID_ALIASES` | Comma-separated binary names mapping to droid target |
| `CCS_DROID_PATH` | Explicit path to droid binary |
| `CCS_TARGET_ALIASES` | Unified alias map (e.g., `codex=mycodex`) |
| `CCS_CODEX_ALIASES` | Legacy comma-separated binary names for codex target |
### Advanced Options
| Variable | Description |
| -------------------- | ---------------------------------------- |
| `CCS_UNIFIED_CONFIG` | Enable unified config mode (config.yaml) |
| `CCS_MIGRATE` | Trigger automatic migration on startup |
| `CCS_SKIP_MIGRATION` | Skip automatic migration |
| `CCS_SKIP_PREFLIGHT` | Skip API key validation checks |
| `CCS_WEBSEARCH_SKIP` | Skip WebSearch hook integration |
| `CCS_PROFILE_TYPE` | Signal profile type to WebSearch hook |
## Configuration Paths
| Path | Description |
| ------------------------ | ------------------------------- |
| `~/.ccs/config.yaml` | Main configuration file |
| `~/.ccs/instances/` | Isolated Claude instances |
| `~/.ccs/*.settings.json` | API profile settings |
| `~/.ccs/shared/` | Shared commands, skills, agents |
## Shared Data Structure
```
~/.ccs/shared/
├── commands/ # Custom commands (symlinked)
├── skills/ # Custom skills (symlinked)
└── agents/ # Custom agents (symlinked)
```
On Windows, copies are used instead of symlinks if symlinks are unavailable.
## Exit Codes
CCS uses standardized exit codes following Unix conventions:
| Code | Meaning | Description |
| ---- | ---------------- | ----------------------------------------------------------------------- |
| 0 | SUCCESS | Successful execution |
| 1 | GENERAL\_ERROR | General/unspecified error |
| 2 | CONFIG\_ERROR | Configuration file errors (missing, invalid, corrupt) |
| 3 | NETWORK\_ERROR | Network-related errors (connection, timeout, DNS) |
| 4 | AUTH\_ERROR | Authentication/authorization errors (invalid token, expired, forbidden) |
| 5 | BINARY\_ERROR | Binary/executable errors (missing Claude CLI, corrupted binary) |
| 6 | PROVIDER\_ERROR | Provider-specific errors (API errors, rate limits, service unavailable) |
| 7 | PROFILE\_ERROR | Profile not found or invalid |
| 8 | PROXY\_ERROR | Proxy-related errors (startup failure, port conflict) |
| 9 | MIGRATION\_ERROR | Migration errors (failed to migrate config) |
| 130 | USER\_ABORT | User aborted operation (Ctrl+C, SIGINT) |
# CLI Flags Reference
Source: https://docs.ccs.kaitran.ca/reference/cli-flags
Complete reference for all CCS CLI flags including account management, remote proxy configuration, and provider-specific options
# CLI Flags Reference
Complete reference for all CLI flags available in CCS. Flags can be combined with profile names and commands.
## Overview
CCS CLI flags provide runtime configuration for authentication, proxy behavior, and provider-specific features. Flags override config file settings and follow this priority:
**CLI Flags > Environment Variables > config.yaml > Defaults**
***
## Account Management Flags
Manage multiple OAuth accounts for CLIProxy providers (`gemini`, `codex`,
`xai`, `agy`, `iflow`, `kiro`, `claude`, `kimi`, `cursor`, `gitlab`,
`codebuddy`, `kilo`, `qoder`) plus deprecated `ghcp` compatibility.
`grok` accepts the same account and model flags as `xai` and uses the same
`xai` account state.
### `--use `
**Scope:** All OAuth providers
**Purpose:** Switch active account for profile execution
**Priority:** HIGH
```bash theme={null}
ccs codex --use work@example.com
```
**Behavior:**
* Temporarily uses specified account instead of default
* Does NOT change default account in config
* Account must exist (use `--accounts` to list)
* Nickname or email accepted
**Related:** `--accounts`, `--nickname`, `ccs auth default`
***
### `--accounts`
**Scope:** All OAuth providers
**Purpose:** List all registered accounts with metadata
**Priority:** HIGH
```bash theme={null}
ccs codex --accounts
ccs kiro --accounts
```
**Output:**
* Email addresses when token metadata provides them
* Derived account IDs or nicknames when an email is unavailable (including xAI)
* Nicknames (if set)
* Last used timestamp
* Default account indicator
**Related:** `--use`, `ccs auth list`
***
### `--nickname `
**Scope:** All OAuth providers
**Purpose:** Rename account with human-friendly alias
**Priority:** MEDIUM
```bash theme={null}
ccs codex --nickname work
ccs codex --use bob@company.com --nickname work-bob
```
**Behavior:**
* Sets nickname for current/specified account
* Nickname stored in `config.yaml` under `cliproxy.oauth_accounts`
* Can use nickname in `--use` flag after setting
* Must be unique across accounts
**Related:** `--use`, `--accounts`
***
### `--auth`
**Scope:** All OAuth providers
**Purpose:** Manually trigger OAuth flow
**Priority:** MEDIUM
```bash theme={null}
ccs codex --auth # Re-authenticate default account
ccs kiro --auth --add # Add new account
```
**Behavior:**
* Starts browser-callback or device-code OAuth, depending on provider
* Refreshes expired tokens
* Updates credentials in CLIProxy session storage
* Shows success/error message
**Use Cases:**
* Token expired or revoked
* Session became invalid
* Testing authentication
**Related:** `--logout`, `--add`
***
### `--logout`
**Scope:** All OAuth providers
**Purpose:** Remove account credentials and session
**Priority:** MEDIUM
```bash theme={null}
ccs codex --logout
ccs kimi --use old@example.com --logout
```
**Behavior:**
* Removes OAuth tokens from session storage
* Does NOT remove account from `config.yaml`
* Requires re-authentication on next use
* Safe to run multiple times
**Related:** `--auth`, `ccs auth remove`
***
### `--add` (with --auth)
**Scope:** All OAuth providers
**Purpose:** Add new account while keeping existing
**Priority:** MEDIUM
```bash theme={null}
ccs codex --auth --add
ccs kiro --auth --add --nickname work-alt
```
**Behavior:**
* Opens browser for new OAuth flow
* Adds account to `config.yaml`
* Does NOT replace existing accounts
* Can set nickname immediately
**Related:** `--auth`, `--nickname`, `ccs auth create`
***
## Remote Proxy Flags
Configure connection to remote CLIProxyAPI server instead of local binary.
### `--proxy-host`
**Scope:** CLIProxy profiles and variants
**Purpose:** Remote proxy hostname or IP
**Priority:** HIGH
```bash theme={null}
ccs codex --proxy-host proxy.example.com
ccs codex --proxy-host 192.168.1.100
```
**Behavior:**
* Overrides `config.cliproxy_server.remote.host`
* Requires valid hostname/IP (no protocol prefix)
* Auto-detects protocol if port 443 (HTTPS) or 80 (HTTP)
* Falls back to local if unreachable (unless `--remote-only`)
**Related:** `--proxy-port`, `--proxy-protocol`, `CCS_PROXY_HOST`
***
### `--proxy-port`
**Scope:** CLIProxy profiles and variants
**Purpose:** Remote proxy port number
**Priority:** HIGH
```bash theme={null}
ccs codex --proxy-host proxy.example.com --proxy-port 8443
ccs codex --proxy-host 192.168.1.100 --proxy-port 80
```
**Behavior:**
* Overrides `config.cliproxy_server.remote.port`
* Defaults: 443 (HTTPS), 80 (HTTP) if not specified
* Must be valid port (1-65535)
**Related:** `--proxy-host`, `CCS_PROXY_PORT`
***
### `--proxy-auth-token`
**Scope:** CLIProxy profiles and variants
**Purpose:** Authentication token for remote proxy
**Priority:** HIGH
```bash theme={null}
ccs codex --proxy-host proxy.example.com --proxy-auth-token
```
**Behavior:**
* Overrides `config.cliproxy_server.remote.auth_token`
* Sent in `Authorization` header
* Required if remote proxy has auth enabled
* Can be API key or JWT
**Security:** Do NOT commit tokens to version control
**Related:** `--proxy-host`, `CCS_PROXY_AUTH_TOKEN`
***
### `--proxy-protocol`
**Scope:** CLIProxy profiles and variants
**Purpose:** Remote proxy protocol (http/https)
**Priority:** MEDIUM
```bash theme={null}
ccs codex --proxy-host proxy.example.com --proxy-protocol https
```
**Behavior:**
* Overrides `config.cliproxy_server.remote.protocol`
* Values: `http`, `https`
* Default: `http` (unless port 443)
* **When set to `https`:** Automatically starts HTTP→HTTPS tunnel (see [Remote Proxy HTTPS Tunnel](/features/proxy/remote-proxy#https-tunnel))
**Related:** `--proxy-host`, `CCS_PROXY_PROTOCOL`, `--allow-self-signed`
***
### `--proxy-timeout`
**Scope:** CLIProxy profiles and variants
**Purpose:** Health check timeout in milliseconds
**Priority:** LOW
```bash theme={null}
ccs codex --proxy-host proxy.example.com --proxy-timeout 5000
```
**Behavior:**
* Overrides `config.cliproxy_server.remote.timeout`
* Default: 2000ms (2 seconds)
* Used for initial health check only
* Higher values for slow networks
**Related:** `--proxy-host`, `CCS_PROXY_TIMEOUT`
***
### `--local-proxy`
**Scope:** CLIProxy profiles and variants
**Purpose:** Force local CLIProxy mode
**Priority:** MEDIUM
```bash theme={null}
ccs codex --local-proxy
```
**Behavior:**
* Disables remote proxy even if configured
* Spawns local CLIProxyAPI binary
* Useful for testing or offline work
* Ignores `config.cliproxy_server.remote` settings
**Related:** `--remote-only`, `--proxy-host`
***
### `--remote-only`
**Scope:** CLIProxy profiles and variants
**Purpose:** Fail if remote proxy unreachable
**Priority:** MEDIUM
```bash theme={null}
ccs codex --proxy-host proxy.example.com --remote-only
```
**Behavior:**
* Disables fallback to local proxy
* Exit with `PROXY_ERROR` if remote unreachable
* Useful for enforcing remote proxy usage
* Overrides `config.cliproxy_server.fallback.enabled`
**Related:** `--local-proxy`, `--proxy-host`
***
### `--allow-self-signed`
**Scope:** CLIProxy profiles and variants
**Purpose:** Accept self-signed SSL certificates
**Priority:** LOW
```bash theme={null}
ccs codex --proxy-host proxy.example.com --proxy-protocol https --allow-self-signed
```
**Behavior:**
* Disables SSL certificate validation
* Required for dev/test environments with self-signed certs
* **Security Risk:** Only use in trusted environments
**Related:** `--proxy-protocol`, `CCS_ALLOW_SELF_SIGNED`
***
## Browser Automation Flags
### `--browser`
**Scope:** Claude-target and Codex-target launches
**Purpose:** Expose configured browser tooling for this launch
**Priority:** HIGH
```bash theme={null}
ccs glm --browser "inspect the page"
ccs default --target codex --browser "use browser tools"
```
**Behavior:**
* Forces browser tooling on for the current launch when that lane is enabled
* Does not change saved `browser..policy`
* Fails safe with guidance if the selected lane is disabled or not ready
**Related:** `ccs browser setup`, [Browser Automation](/features/workflow/browser-automation)
***
### `--no-browser`
**Scope:** Claude-target and Codex-target launches
**Purpose:** Suppress configured browser tooling for this launch
**Priority:** HIGH
```bash theme={null}
ccs glm --no-browser "summarize the docs"
```
**Behavior:**
* Keeps browser tooling hidden for the current launch even when policy is `auto`
* Useful for privacy-sensitive runs or quick non-browser tasks
* Cannot be combined with `--browser`
**Related:** `browser.claude.policy`, `browser.codex.policy`
***
## Runtime Target Flags
### `--target `
**Scope:** All supported profiles except `cliproxy`, `copilot`, and `account`
**Purpose:** Route profile to alternative CLI target
**Priority:** HIGH
```bash theme={null}
ccs glm --target droid # Route to Droid CLI
ccs codex --target codex # Route to native Codex CLI
ccs codex --target=droid # Supports both formats
ccs glm --target claude # Explicit Claude (default)
```
**Behavior:**
* `claude` (default): Launch via Claude Code CLI
* `droid`: Launch via Droid CLI (`@factory/cli`)
* `codex`: Launch via native Codex CLI (transient credentials, no file rewrites)
* `ccsxp` shortcut: Forces `ccs codex --target codex`, strips any user `--target` override
* Overrides per-profile `target` config and argv0 detection
* Binary located via `CCS_DROID_PATH` or PATH lookup (droid), or PATH lookup (codex)
* Legacy `glmt` compatibility profiles follow the normal settings-profile target flow after runtime normalization
**Related:** `CCS_DROID_PATH`, `CCS_DROID_ALIASES`, `CCS_TARGET_ALIASES`, [Droid Adapter](/features/workflow/droid-adapter), [Codex Adapter](/features/workflow/codex-adapter)
***
### `--permission-mode ` (persist)
**Scope:** All profiles
**Purpose:** Set Claude permission mode (persisted to session)
**Priority:** HIGH
```bash theme={null}
ccs codex --permission-mode bypassPermissions
ccs glm --permission-mode plan
ccs claude --permission-mode acceptEdits
```
**Valid values:** `default`, `plan`, `acceptEdits`, `bypassPermissions`
**Related:** `--dangerously-skip-permissions`, `--auto-approve`
***
### `--dangerously-skip-permissions` / `--auto-approve`
**Scope:** All profiles
**Purpose:** Equivalent to `--permission-mode bypassPermissions`
**Priority:** HIGH
```bash theme={null}
ccs codex --dangerously-skip-permissions
ccs codex --auto-approve # Alias
```
**Behavior:** Bypasses all Claude permission prompts. Use with caution in automated environments.
***
### `--kimi`
**Scope:** `/ccs` delegation command
**Purpose:** Force Kimi OAuth (CLIProxy) for long context
**Priority:** MEDIUM
```bash theme={null}
/ccs --kimi "analyze large codebase"
```
**Behavior:** Delegation flag — routes request through Kimi OAuth provider when long context is needed.
***
### `--km`
**Scope:** `/ccs` delegation command
**Purpose:** Force Kimi API key (direct) for long context
**Priority:** MEDIUM
```bash theme={null}
/ccs --km "analyze large codebase"
```
**Behavior:** Delegation flag — routes request through Kimi for Coding API (`ccs km`) when long context is needed.
***
### `--thinking `
**Scope:** All profiles
**Purpose:** Enable extended thinking mode
**Priority:** HIGH (overrides `CCS_THINKING` env and config)
```bash theme={null}
ccs claude --thinking 20000 # 20k token budget
ccs claude --thinking high # Level name
ccs claude --thinking max # Adaptive ceiling on supported models
ccs codex --thinking off # Disable thinking
```
**Behavior:**
* Enables extended thinking for compatible models
* Accepts token budget number (e.g., 5000, 20000) or level name (minimal, low, medium, high, xhigh, max, auto)
* `max` stays distinct on models that expose it, such as Claude Fable 5 and Opus 4.8; models without a native max level map it to their supported ceiling
* Off values: `off`, `none`, `disabled`, `0` — all equivalent, disable thinking
* Overrides `CCS_THINKING` env var and `thinking` config section
* Ignored by models without thinking support
* Native Claude one-session effort overrides are documented separately under
`--effort`
**Related:** `CCS_THINKING` env var, `ccs config thinking`, [Extended Thinking](/features/ai/extended-thinking)
***
### `--effort `
**Scope:** Native Claude launches, plus Codex compatibility flows
**Purpose:** Apply a one-session reasoning effort override
**Priority:** HIGH
```bash theme={null}
ccs --effort high "debug this"
ccs work --effort max "review this architecture"
ccs codex --effort xhigh "deep analysis"
```
**Behavior:**
* On native Claude launches, CCS validates `low|medium|high|xhigh|max`,
normalizes the value, and forwards it without mutating Claude or CCS config
files
* On Codex and other CCS thinking flows, `--effort` remains a compatibility
alias of `--thinking`
* Missing or invalid values fail fast before the runtime is spawned
**Related:** `--thinking`, [Extended Thinking](/features/ai/extended-thinking)
***
### `--1m` / `--no-1m`
**Scope:** All profiles
**Purpose:** Enable/disable 1M token extended context window
**Priority:** MEDIUM
```bash theme={null}
ccs claude --1m "analyze large codebase" # Enable 1M context
ccs claude --no-1m "quick summary" # Disable 1M context
ccs claude --1m # Interactive with 1M enabled
```
**Behavior:**
* `--1m`: Enables 1M token context window via \[1m] model suffix
* `--no-1m`: Disables 1M token context window (removes \[1m] suffix)
* **Auto-enabled:** Native Gemini models (e.g., gemini-3-pro) have 1M enabled by default
* **Opt-in:** Claude models require explicit `--1m` flag to use extended context
* **Overrides:** CLI flag takes priority over provider config settings
* **Warning:** Shows warning if model doesn't support extended context
**Supported Models:**
* Claude Opus 4.6 (auto-detect from model catalog)
* Claude Sonnet 4.5 (with --1m flag)
* Gemini 3 Pro (auto-enabled)
* Gemini 2.0 (auto-enabled)
**Technical Details:**
* Extended context uses model suffix format: `claude-opus-4-6[1m]`
* Requires compatible Claude Code version supporting \[1m] suffix
* Token budget remains 1M even if context window is smaller
**Related:** Extended context feature, model catalogs, provider documentation
***
### `--headless`
**Scope:** OAuth providers (gemini, codex, agy, kiro, etc.)
**Purpose:** OAuth without browser, display URL for manual authentication
**Priority:** LOW
```bash theme={null}
ccs kiro --auth --headless
ccs codex --auth --add --headless
```
**Behavior:**
* Skips automatic browser launch during OAuth
* Displays OAuth URL in terminal for manual copying
* Useful for SSH sessions without browser access
* User opens URL in external browser, completes auth
* Callback providers wait for a local callback; xAI displays a device URL and
verification code, then polls without a local callback port
**Use Cases:**
* Remote SSH sessions
* CI/CD environments without browser
* Headless servers
**Related:** `--auth`, `--incognito`
***
### `--incognito`
**Scope:** Kiro provider
**Purpose:** Force incognito browser mode for OAuth
**Priority:** LOW
```bash theme={null}
ccs kiro --auth --incognito
```
**Behavior:**
* Opens browser in incognito/private mode
* Prevents cookie/session persistence
* Opposite of `--no-incognito` flag
* Useful for testing or multi-account isolation
**Related:** `--no-incognito`, `--auth`
***
## Provider-Specific Flags
Flags available only for specific providers.
### `--backend ` (`ccs cliproxy`)
**Scope:** `ccs cliproxy` commands
**Purpose:** Override CLIProxy backend selection
**Priority:** HIGH
```bash theme={null}
ccs cliproxy status --backend original # Use CLIProxyAPI
ccs cliproxy status --backend plus # Use CLIProxyAPIPlus
```
**Behavior:**
* Overrides `config.cliproxy.backend` setting
* Values: `original` | `plus`
* **Plus required** for `kiro`, `cursor`, `gitlab`, `codebuddy`, `kilo`,
`qoder`, and deprecated `ghcp` compatibility
* `xai` works with `original` and is not Plus-only
* Backend-specific binaries auto-downloaded if needed
* Generated local CLIProxy config selects the matching embedded CPAMC dashboard
repository for the chosen backend
**Use Cases:**
* Test different backends without changing config
* Force specific backend for troubleshooting
* Ensure plus-only provider compatibility
**Related:** `config.cliproxy.backend`, provider compatibility
***
### `--import` (Kiro only)
**Scope:** Kiro provider
**Purpose:** Import OAuth token from Kiro IDE
**Priority:** HIGH
```bash theme={null}
ccs kiro --import
```
**Behavior:**
* Reads token from Kiro IDE config location
* Bypasses browser OAuth flow
* Faster authentication if IDE already logged in
* Falls back to browser if import fails
**Requirements:**
* Kiro IDE installed and authenticated
* Token file accessible
**Related:** `--auth`, Kiro provider docs
***
### `--config` (Supported providers)
**Scope:** Catalog-backed CLIProxy providers (`agy`, `claude`, `codex`, `gemini`, `kimi`, `qoder`, `xai`; `grok` is an alias for `xai`)
**Purpose:** Launch interactive model configuration UI
**Priority:** MEDIUM
```bash theme={null}
ccs codex --config
ccs xai --config
```
**Behavior:**
* Opens terminal UI for model selection
* Shows available models with metadata
* Updates `config.yaml` with selected model
* Validates model availability
**Related:** Gemini provider docs
***
### `--gitlab-token-login` / `--token-login` (GitLab only)
**Scope:** GitLab Duo provider
**Purpose:** Authenticate with a GitLab Personal Access Token instead of browser OAuth
**Priority:** HIGH
```bash theme={null}
ccs gitlab --auth --gitlab-token-login
ccs gitlab --auth --token-login # legacy alias
```
**Behavior:**
* switches GitLab auth into PAT mode
* bypasses the normal browser OAuth path
* useful for self-hosted or automation-heavy GitLab setups
**Related:** `--gitlab-url`, `--auth`
***
### `--gitlab-url ` (GitLab only)
**Scope:** GitLab Duo provider
**Purpose:** Use a custom GitLab base URL during auth
**Priority:** HIGH
```bash theme={null}
ccs gitlab --auth --gitlab-url https://gitlab.example.com
```
**Behavior:**
* targets self-hosted GitLab instead of `gitlab.com`
* works with browser OAuth or PAT login
* CCS switches to paste-callback mode when the custom OAuth flow cannot rely on the normal local callback path
**Related:** `--gitlab-token-login`, `--auth`, `--paste-callback`
***
### `--no-incognito` (Kiro only)
**Scope:** Kiro provider
**Purpose:** Use normal browser mode instead of incognito
**Priority:** MEDIUM
```bash theme={null}
ccs kiro --no-incognito
```
**Behavior:**
* Opens browser in normal mode (saves cookies/session)
* Useful for persistent AWS SSO login
* Overrides `config.cliproxy.kiro_no_incognito`
* Browser profile persists between sessions
**Use Case:** Avoid re-entering AWS credentials for Kiro authentication
**Related:** `config.cliproxy.kiro_no_incognito`
***
## CLIProxy Diagnostic Flags
Flags for debugging CLIProxy behavior and quota fetching.
### `--verbose`, `-v`
**Scope:** CLIProxy commands (`ccs cliproxy`, provider commands)
**Purpose:** Enable detailed diagnostics
**Priority:** LOW
```bash theme={null}
ccs cliproxy status --verbose
ccs codex --verbose
```
**Output includes:**
* Token refresh attempts with timestamps
* Project ID resolution details
* Model quota API calls and responses
* Error details with HTTP status codes
**Use Cases:**
* Debugging quota fetch failures
* Investigating token refresh issues
* Troubleshooting "N/A (fetch unavailable)" quota display
**Related:** `ccs cliproxy status`, `ccs cliproxy quota`, [GLMT Deprecation](/features/ai/glmt-controls)
***
## Persist Command Flags
Flags for the `ccs persist` command that manages settings.json persistence.
### `--yes`, `-y`
**Scope:** persist command
**Purpose:** Skip confirmation prompts, auto-backup before modification
**Priority:** MEDIUM
```bash theme={null}
ccs persist glm --yes
ccs persist glm -y
```
**Behavior:**
* Skips interactive confirmation
* Automatically creates backup before changes
* Useful for automation and scripts
**Related:** `ccs persist`, `--list-backups`, `--restore`
***
### `--list-backups`
**Scope:** persist command
**Purpose:** List all available settings.json backup files
**Priority:** LOW
```bash theme={null}
ccs persist --list-backups
```
**Output:**
```
Available backups:
[latest] 20260114_120534 (2026-01-14 12:05:34)
20260113_093021 (2026-01-13 09:30:21)
20260112_155612 (2026-01-12 15:56:12)
To restore: ccs persist --restore [timestamp]
```
**Related:** `--restore`, `ccs persist`
***
### `--restore [timestamp]`
**Scope:** persist command
**Purpose:** Restore settings.json from backup
**Priority:** MEDIUM
```bash theme={null}
# Restore from latest backup
ccs persist --restore
# Restore from specific backup
ccs persist --restore 20260113_093021
```
**Behavior:**
* Validates JSON integrity before restore
* Rejects symlinked backup files (security)
* Creates backup of current settings before restore
* Confirms restore success with timestamp
**Use Cases:**
* Recovering from incorrect persist operation
* Reverting to known-good configuration
* Testing configuration changes safely
**Related:** `--list-backups`, `ccs persist`
***
### `--paste-callback`
**Scope:** OAuth providers
**Purpose:** Show auth URL and prompt for callback URL paste instead of auto-redirect
**Priority:** LOW
```bash theme={null}
ccs codex --auth --paste-callback
ccs kiro --auth --paste-callback
```
**Behavior:**
* Displays OAuth URL in terminal
* Waits for user to paste the full callback URL after completing auth in browser
* Useful when CCS cannot receive the OAuth redirect directly (e.g., reverse proxy setups)
* Alternative to `--headless` for environments where callback interception is blocked
* xAI uses device-code OAuth, so it does not require callback forwarding
**Related:** `--headless`, `--auth`
***
### `--port-forward`
**Scope:** OAuth providers
**Purpose:** Force port-forwarding mode for OAuth callback
**Priority:** LOW
```bash theme={null}
ccs codex --auth --port-forward
```
**Behavior:**
* Forces CCS to use port-forwarding for the OAuth callback listener
* Required in some container or remote environment setups where direct port binding fails
* CCS listens on a forwarded port instead of a standard local port
* Not needed for xAI device-code OAuth
**Related:** `--headless`, `--paste-callback`
***
### `--accept-agr-risk`
**Scope:** Antigravity (agy) provider
**Purpose:** Bypass Antigravity confirmation prompt
**Priority:** MEDIUM
```bash theme={null}
ccs agy --accept-agr-risk "your prompt"
```
**Behavior:**
* Skips the one-time risk acknowledgment prompt for Antigravity provider
* Stores acceptance in config so subsequent runs do not prompt again
* Use in automation/CI where interactive prompts are not acceptable
**Related:** Antigravity provider docs, `ccs agy`
***
### `--kiro-auth-method `
**Scope:** Kiro provider
**Purpose:** Select Kiro authentication method
**Priority:** HIGH
```bash theme={null}
ccs kiro --kiro-auth-method aws # AWS device code (default)
ccs kiro --kiro-auth-method aws-authcode # AWS authorization code flow
ccs kiro --kiro-auth-method google # Google OAuth
ccs kiro --kiro-auth-method idc # IAM Identity Center
```
**Values:**
| Method | Description |
| -------------- | ------------------------------------------------------------ |
| `aws` | AWS device code flow (default, recommended) |
| `aws-authcode` | AWS authorization code flow |
| `google` | Google OAuth |
| `idc` | IAM Identity Center flow; requires `--kiro-idc-start-url` |
| `github` | Dashboard-only management flow, not a direct CLI launch path |
**Behavior:**
* Selects which identity provider to use for Kiro authentication
* AWS device code (`aws`) is recommended for most setups
* `idc` requires a start URL and optionally accepts region and flow overrides
* Callback-based methods pair well with `--paste-callback`
**Related:** `--auth`, `--import`, `--incognito`, `--no-incognito`
***
### `--kiro-idc-start-url `
**Scope:** Kiro provider
**Purpose:** Required start URL for Kiro IDC authentication
**Priority:** HIGH
```bash theme={null}
ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start
```
**Behavior:**
* Required whenever `--kiro-auth-method idc` is used
* Points CCS at the correct AWS Identity Center tenant
**Related:** `--kiro-auth-method`, `--kiro-idc-region`, `--kiro-idc-flow`
***
### `--kiro-idc-region `
**Scope:** Kiro provider
**Purpose:** Optional region override for Kiro IDC
**Priority:** MEDIUM
```bash theme={null}
ccs kiro --auth --kiro-auth-method idc \
--kiro-idc-start-url https://d-xxx.awsapps.com/start \
--kiro-idc-region us-east-1
```
**Behavior:**
* Overrides the default region inferred by the upstream flow
* Only valid with `--kiro-auth-method idc`
**Related:** `--kiro-auth-method`, `--kiro-idc-start-url`
***
### `--kiro-idc-flow `
**Scope:** Kiro provider
**Purpose:** Choose IDC auth-code vs device-code flow
**Priority:** MEDIUM
```bash theme={null}
ccs kiro --auth --kiro-auth-method idc \
--kiro-idc-start-url https://d-xxx.awsapps.com/start \
--kiro-idc-flow device
```
**Behavior:**
* Defaults to `authcode`
* Use `device` only when you explicitly need the device-code variant
**Related:** `--kiro-auth-method`, `--kiro-idc-start-url`
***
## Flag Combinations
Common flag combinations for typical workflows.
### Multi-Account Workflow
```bash theme={null}
# List accounts
ccs codex --accounts
# Switch account for single run
ccs codex --use work@example.com
# Add new account with nickname
ccs codex --auth --add --nickname personal
# Use new account
ccs codex --use personal
```
### Remote Proxy Setup
```bash theme={null}
# Basic remote proxy
ccs codex --proxy-host proxy.example.com --proxy-port 8443 --proxy-auth-token
# HTTPS with self-signed cert
ccs codex --proxy-host proxy.example.com --proxy-protocol https --allow-self-signed
# Remote-only (no fallback)
ccs codex --proxy-host proxy.example.com --remote-only
```
### Provider-Specific Workflows
```bash theme={null}
# Kiro with token import and persistent browser
ccs kiro --import --no-incognito
# Kiro IDC auth with explicit start URL
ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start
# Codex with model configuration
ccs codex --config
```
### Diagnostic & Persist Workflows
```bash theme={null}
# Verbose CLIProxy diagnostics
ccs cliproxy status --verbose
ccs codex --verbose
# Persist settings with auto-confirmation
ccs persist glm --yes
# List and restore from backups
ccs persist --list-backups
ccs persist --restore 20260113_093021
```
***
## Environment Variable Equivalents
Many flags have environment variable equivalents for persistent configuration.
| Flag | Environment Variable | Config Key |
| ---------------------------- | -------------------------------------------------- | ----------------------------------- |
| `--proxy-host` | `CCS_PROXY_HOST` | `cliproxy_server.remote.host` |
| `--proxy-port` | `CCS_PROXY_PORT` | `cliproxy_server.remote.port` |
| `--proxy-auth-token` | `CCS_PROXY_AUTH_TOKEN` | `cliproxy_server.remote.auth_token` |
| `--proxy-protocol` | `CCS_PROXY_PROTOCOL` | `cliproxy_server.remote.protocol` |
| `--proxy-timeout` | `CCS_PROXY_TIMEOUT` | `cliproxy_server.remote.timeout` |
| `--allow-self-signed` | `CCS_ALLOW_SELF_SIGNED` | N/A |
| `--browser` / `--no-browser` | N/A | `browser..policy` |
| `--no-incognito` | N/A | `cliproxy.kiro_no_incognito` |
| `--target droid` | `CCS_DROID_ALIASES` (argv0) / `CCS_DROID_PATH` | `profiles..target` |
| `--target codex` | `CCS_TARGET_ALIASES` / `CCS_CODEX_ALIASES` (argv0) | `profiles..target` |
| `--thinking` | `CCS_THINKING` | `thinking.override` |
| `--accept-agr-risk` | N/A | N/A (stored in session) |
| `--kiro-auth-method` | N/A | `cliproxy.kiro_auth_method` |
**Priority:** CLI flags override environment variables override config file
### Droid/Target Environment Variables
| Variable | Description |
| -------------------- | ----------------------------------------------------------- |
| `CCS_DROID_ALIASES` | Comma-separated argv0 binary names that map to droid target |
| `CCS_DROID_PATH` | Explicit absolute path to the droid binary |
| `CCS_TARGET_ALIASES` | Unified alias map (e.g., `codex=mycodex`) |
| `CCS_CODEX_ALIASES` | Legacy comma-separated binary names for codex target |
### Thinking Environment Variable
| Variable | Accepted Values |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `CCS_THINKING` | `minimal`, `low`, `medium`, `high`, `xhigh`, `auto`, `off`, `none`, `disabled`, `0`, or integer `0`–`100000` |
***
## Troubleshooting
### Account Flags
**"Account not found" error:**
* Run `ccs --accounts` to list available accounts
* Check spelling of email/nickname
* Verify account was created with `--auth --add`
**Nickname conflicts:**
* Nicknames must be unique across all accounts
* Remove old nickname before setting new one
* Edit `config.yaml` manually if needed
### Remote Proxy Flags
**Connection timeout:**
* Increase `--proxy-timeout` value
* Check network connectivity to host
* Verify host/port are correct
* Try `--local-proxy` to test locally
**SSL certificate errors:**
* Use `--allow-self-signed` for dev/test environments
* Verify certificate is valid in production
* Check `--proxy-protocol` is `https`
**Authentication failures:**
* Verify `--proxy-auth-token` is correct
* Check token hasn't expired
* Test token with `curl` or similar tool
***
## Related Resources
* [CLI Commands Reference](/reference/cli-commands)
* [Configuration Schema](/reference/config-schema)
* [Error Codes](/reference/error-codes)
* [Troubleshooting Guide](/reference/troubleshooting)
# Configuration Schema Reference
Source: https://docs.ccs.kaitran.ca/reference/config-schema
Complete schema reference for the current development config.yaml v14 source
# Configuration Schema Reference
Complete reference for the current development `config.yaml` version 14 source. This does not claim release availability.
**Location:** `~/.ccs/config.yaml`
**Format:** YAML
**Current development source version:** 14
***
## Version History
| Version | Release | Key Changes |
| ------- | ----------- | ------------------------------------------------------------------------ |
| v14 | Current dev | User-defined CLIProxy OAuth aliases and scoped payload override rules |
| v13 | 2026-04 | Browser automation policy and OpenAI-compatible local proxy config |
| v12 | 2026-03 | Official Channels multi-provider support (Telegram, Discord, iMessage) |
| v11 | 2026-03 | Discord Channels runtime auto-enable preferences |
| v9 | 2026-03 | Cross-profile continuity inheritance (`continuity.inherit_from_account`) |
| v8 | 2026-02 | Thinking/reasoning budget configuration, image analysis config |
| v7 | 2025-12 | Quota management for hybrid auto+manual account control |
| v6 | 2025-12 | Customizable auth tokens, variant-specific auth, OAuth model aliases |
| v5 | 2025-10 | Remote proxy configuration |
| v4 | 2025-08 | Copilot API integration, now deprecated compatibility |
| v3 | 2025-06 | WebSearch config with model configuration |
| v2 | 2025-04 | Initial YAML unified format |
| v1 | 2025-02 | Legacy JSON format (deprecated) |
***
## Root Schema
```yaml theme={null}
version: 14 # REQUIRED - Schema version
default: # OPTIONAL - Default profile name
accounts: { ... } # Account-based profiles
profiles: { ... } # API-based profiles
cliproxy: { ... } # OAuth provider configuration and user routing rules
proxy: { ... } # OpenAI-compatible local proxy configuration (v13+)
logging: { ... } # CCS-owned structured runtime logging
preferences: { ... } # User preferences
websearch: { ... } # WebSearch configuration
global_env: { ... } # Global environment variables
copilot: { ... } # Deprecated GitHub Copilot compatibility
cliproxy_server: { ... } # Remote/local proxy configuration
quota_management: { ... } # Quota management (v7+)
thinking: { ... } # Thinking/reasoning budget (v8+)
channels: { ... } # Official Channels runtime auto-enable (v12+)
dashboard_auth: { ... } # Dashboard authentication
browser: { ... } # Browser automation settings (v13+)
image_analysis: { ... } # Image analysis configuration (v8+)
continuity: { ... } # Cross-profile continuity inheritance (v9+)
docker: { ... } # Docker deployment configuration (auto-generated)
```
***
## CLIProxy Configuration
### `cliproxy.backend`
**Type:** String (`original` | `plus`)
**Priority:** HIGH
**Purpose:** Select CLIProxy backend variant
```yaml theme={null}
cliproxy:
backend: original # Default: original
```
**Behavior:**
* `original`: CLIProxyAPI (works for `agy`, `claude`, `codex`, `gemini`, `iflow`, `kimi`, `xai`)
* `plus`: CCS-maintained CLIProxyAPIPlus community fork for plus-only providers. Legacy deleted-upstream Plus installs migrate safely to `original`
* Backend-specific binaries stored in `~/.ccs/cliproxy/bin/original/` and `~/.ccs/cliproxy/bin/plus/`
* Generated local CLIProxy configs also select the matching CPAMC dashboard:
upstream CPAMC for `original`, maintained CCS dashboard fork for `plus`
**Provider Requirements:**
* **Require `backend: plus`:** `kiro`, `cursor`, `gitlab`, `codebuddy`, `kilo`, `qoder`, and deprecated `ghcp` compatibility
* **Work on either backend:** `agy`, `claude`, `codex`, `gemini`, `iflow`, `kimi`, `xai`
Use `provider: xai` in configuration and variant definitions. `grok` is a
CLI-only alias and must not be stored as a provider ID.
**Use Cases:**
* Use `original` for the stable default backend and the standard provider set
* Use `plus` only when you need Kiro, Cursor, GitLab Duo, CodeBuddy, Kilo AI, Qoder, or deprecated GitHub Copilot compatibility
**Related:** `--backend` CLI flag, provider compatibility
***
### `cliproxy.management_panel_repository`
**Type:** String
**Priority:** ADVANCED
**Purpose:** Override the CPAMC dashboard repository written to generated CLIProxy config
```yaml theme={null}
cliproxy:
backend: plus
management_panel_repository: https://github.com/kaitranntt/Cli-Proxy-API-Management-Center
```
**Behavior:**
* When omitted, `backend: original` uses `router-for-me/Cli-Proxy-API-Management-Center`
* When omitted, `backend: plus` uses `kaitranntt/Cli-Proxy-API-Management-Center`
* When set, this value is written to `remote-management.panel-github-repository`
* CCS regenerates stale local CLIProxy config when the expected panel repository changes
**Use Cases:**
* Pin Plus users to the CCS-maintained management dashboard fork
* Test or maintain a private CPAMC fork without editing generated CLIProxy files
**Related:** `cliproxy.backend`, CLIProxy control panel
***
### `cliproxy.variants..target`
**Type:** String (`claude` | `droid`)
**Priority:** HIGH
**Purpose:** Route this variant to an alternative CLI target
```yaml theme={null}
cliproxy:
variants:
my-variant:
provider: gemini
target: droid # Always route to Droid CLI (claude, droid, or codex)
```
**Behavior:**
* `claude` (default): Use Claude Code CLI
* `droid`: Use Droid CLI (`@factory/cli`)
* `codex`: Use OpenAI Codex CLI
* Overridden by `--target` CLI flag
**Also available on:**
* `profiles..target` (API profiles)
* `cliproxy.variants..target` (CLIProxy variant profiles)
* Composite variant configs
**Not supported for:** `cliproxy`, `copilot`, and `account`
***
### `cliproxy.variants..auth`
**Type:** Object
**Priority:** HIGH
**Purpose:** Per-variant auth override
```yaml theme={null}
cliproxy:
variants:
my-gemini:
provider: gemini
auth:
api_key: "custom-key-123"
management_secret: "custom-secret-456"
```
**Behavior:**
* Overrides global `cliproxy.auth` for specific variant
* Useful for different auth credentials per variant
* Both keys optional (falls back to global)
**Use Cases:**
* Separate auth for dev/prod variants
* Per-team auth credentials
* Testing with different API keys
***
### `cliproxy.variants..port`
**Type:** Integer (1-65535, recommended: 8318-8417)
**Priority:** HIGH
**Purpose:** Port isolation for concurrent variants
```yaml theme={null}
cliproxy:
variants:
gemini-dev:
provider: gemini
port: 8318
gemini-prod:
provider: gemini
port: 8319
```
**Behavior:**
* Assigns unique port for variant isolation
* Allows multiple variants to run simultaneously
* Accepts any valid port (1-65535), recommended range: 8318-8417 for CCS variants
* Default: Auto-assigned if not specified
**Use Cases:**
* Run dev and prod variants concurrently
* Isolate variants for different teams
* Avoid port conflicts in multi-user environments
***
### `cliproxy.auth.api_key`
**Type:** String
**Priority:** MEDIUM
**Purpose:** Global API key for CLIProxyAPI
```yaml theme={null}
cliproxy:
auth:
api_key: "ccs-internal-managed" # Default
```
**Behavior:**
* Used for CLIProxyAPI authentication
* Sent in `x-api-key` header
* Can be overridden per-variant via `variants..auth.api_key`
* Default: `"ccs-internal-managed"`
**Security:** Store securely, do not commit to version control
***
### `cliproxy.auth.management_secret`
**Type:** String
**Priority:** MEDIUM
**Purpose:** Global management secret for CLIProxyAPI
```yaml theme={null}
cliproxy:
auth:
management_secret: "ccs" # Default
```
**Behavior:**
* Used for CLIProxyAPI management endpoints
* Sent in `x-management-secret` header
* Can be overridden per-variant via `variants..auth.management_secret`
* Default: `"ccs"`
**Use Cases:**
* Separate auth for management vs API operations
* Enhanced security for admin endpoints
***
### `cliproxy.kiro_no_incognito`
**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Disable incognito mode for Kiro provider
```yaml theme={null}
cliproxy:
kiro_no_incognito: true # Default: true
```
**Behavior:**
* `true`: Use normal browser mode (default, saves cookies/session)
* `false`: Force incognito mode
**Use Cases:**
* Persistent AWS SSO login for Kiro
* Avoid re-entering credentials on each auth
* Development/testing with saved browser state
**Related:** `--no-incognito` CLI flag
***
### `cliproxy.routing.strategy`
**Type:** String (`round-robin` | `fill-first`)
**Priority:** MEDIUM
**Purpose:** Persist the proxy-wide routing strategy CCS should prefer
```yaml theme={null}
cliproxy:
routing:
strategy: round-robin
```
**Behavior:**
* `round-robin`: Spread requests across matching healthy accounts
* `fill-first`: Drain one healthy account before touching backups
* Default stays `round-robin` until you explicitly change it
**Related:** `ccs cliproxy routing`, dashboard `/cliproxy` routing guidance card
***
### `cliproxy.retry`
**Type:** Object
**Priority:** MEDIUM
**Purpose:** Configure CLIProxy request retries globally
```yaml theme={null}
cliproxy:
retry:
request_retry: 0
max_retry_interval: 0
```
| Key | Type | Default | Behavior |
| -------------------- | ------------------------- | ------: | -------------------------------------------------------------------------------------- |
| `request_retry` | Non-negative safe integer | `0` | Retries requests after transient `403`, `408`, `500`, `502`, `503`, or `504` responses |
| `max_retry_interval` | Non-negative safe integer | `0` | Maximum wait, in seconds, for a cooled credential before retrying |
`0` / `0` keeps retries disabled. Invalid persisted values fall back to `0`
when CCS generates local CLIProxy configuration. These values apply to the
whole CLIProxy target, not individual providers. Retrying `403` responses can
consume additional quota in multi-account pools.
For a local target, CCS persists this block, regenerates the local CLIProxy
configuration, and attempts a live update. If live application fails, CCS
reports a config-only result and keeps the generated values for the next proxy
start. For a remote target, CCS applies and persists the values through the
remote management API without writing local `cliproxy.retry` configuration.
This is separate from `max-retry-credentials`, which caps the number of pool
credentials attempted for a single request.
**Related:** dashboard `/cliproxy` routing card, [Account Pools](/features/pool)
***
### `cliproxy.logging.enabled`
**Type:** Boolean
**Priority:** LOW
**Purpose:** Enable CLIProxy logging to disk
```yaml theme={null}
cliproxy:
logging:
enabled: false # Default: false
```
**Behavior:**
* `false`: No disk logging (default, prevents bloat)
* `true`: Write logs to `~/.ccs/cliproxy/logs/`
**Warning:** Logging can consume significant disk space. Enable only for debugging.
***
### `cliproxy.logging.request_log`
**Type:** Boolean
**Priority:** LOW
**Purpose:** Enable detailed request logging
```yaml theme={null}
cliproxy:
logging:
enabled: true
request_log: false # Default: false
```
**Behavior:**
* `false`: Log errors/warnings only
* `true`: Log all HTTP requests/responses
* Requires `logging.enabled: true`
**Warning:** Very verbose. Use only for troubleshooting specific issues.
***
## CCS Logging Configuration
Top-level `logging` controls CCS-owned structured runtime logs. This is separate
from `cliproxy.logging`, which controls CLIProxy runtime files.
### `logging.enabled`
**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Enable CCS-owned structured runtime logging
```yaml theme={null}
logging:
enabled: true
```
### `logging.level`
**Type:** String (`error` | `warn` | `info` | `debug`)
**Priority:** MEDIUM
**Purpose:** Minimum log level written to disk
```yaml theme={null}
logging:
level: info
```
### `logging.rotate_mb`
**Type:** Integer
**Priority:** LOW
**Purpose:** Rotate the current log file when it reaches this size in MB
```yaml theme={null}
logging:
rotate_mb: 10
```
### `logging.retain_days`
**Type:** Integer
**Priority:** LOW
**Purpose:** Keep archived log segments for this many days
```yaml theme={null}
logging:
retain_days: 7
```
### `logging.redact`
**Type:** Boolean
**Priority:** HIGH
**Purpose:** Redact sensitive values before persistence
```yaml theme={null}
logging:
redact: true
```
### `logging.live_buffer_size`
**Type:** Integer
**Priority:** LOW
**Purpose:** Keep this many recent entries in memory for dashboard reads
```yaml theme={null}
logging:
live_buffer_size: 250
```
***
### `cliproxy.token_refresh.enabled`
**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Enable background token refresh worker
```yaml theme={null}
cliproxy:
token_refresh:
enabled: false # Default: false
```
**Behavior:**
* `false`: On-demand refresh only (5 min before expiry)
* `true`: Background worker refreshes tokens at intervals
**Use Cases:**
* Long-running services needing proactive refresh
* Preventing mid-request token expiry
* CI/CD environments with extended sessions
***
### `cliproxy.token_refresh.interval_minutes`
**Type:** Integer (minutes)
**Priority:** LOW
**Purpose:** Background refresh check interval
```yaml theme={null}
cliproxy:
token_refresh:
enabled: true
interval_minutes: 30 # Default: 30
```
**Behavior:**
* Worker checks all tokens every N minutes
* Only refreshes tokens approaching expiry
***
### `cliproxy.token_refresh.preemptive_minutes`
**Type:** Integer (minutes)
**Priority:** LOW
**Purpose:** Refresh tokens expiring within N minutes
```yaml theme={null}
cliproxy:
token_refresh:
enabled: true
preemptive_minutes: 45 # Default: 45
```
**Behavior:**
* Tokens expiring within this window are refreshed
* Higher values = more proactive refresh
* Prevents `UND_ERR_SOCKET` errors from stale tokens
***
### `cliproxy.token_refresh.max_retries`
**Type:** Integer
**Priority:** LOW
**Purpose:** Maximum refresh retry attempts
```yaml theme={null}
cliproxy:
token_refresh:
enabled: true
max_retries: 3 # Default: 3
```
**Behavior:**
* Retries on transient failures
* Logs warning after max retries exceeded
* Does not re-authenticate (requires user action)
***
### `cliproxy.token_refresh.verbose`
**Type:** Boolean
**Priority:** LOW
**Purpose:** Enable debug logging for token refresh
```yaml theme={null}
cliproxy:
token_refresh:
enabled: true
verbose: true # Default: false
```
**Behavior:**
* Logs all refresh attempts to console
* Useful for debugging token issues
* Output: timestamps, providers, success/failure
***
### `cliproxy.oauth_model_alias`
**Type:** Object
**Priority:** HIGH
**Purpose:** Store provider-scoped OAuth model aliases in the CCS unified config
```yaml theme={null}
cliproxy:
oauth_model_alias:
codex:
- name: gpt-5.6-sol
alias: gpt-5.6-sol-fast
fork: true
future-provider:
- name: upstream-model
alias: client-model
```
**Behavior:**
* `cliproxy.oauth_model_alias` is the CCS unified config key
* CCS generates the upstream `oauth-model-alias` block inside local CLIProxy config from this structured input
* Each provider maps to an ordered array of `{ name, alias, fork? }`
* `name` is the upstream model ID, `alias` is the client-visible model ID, and `fork: true` keeps both names visible when upstream supports it
* Entries are deduplicated and replaced by client `alias` within each provider
* Configured aliases replace matching generated aliases in place, while unmatched existing aliases and provider sections stay in order
* Unknown provider sections are preserved during regeneration
**Why This Matters:**
* Lets CCS keep user-owned aliases separate from generated upstream config
* Prevents regeneration from deleting custom provider alias sections
* Supports a Codex fast alias such as `gpt-5.6-sol-fast` without inventing a new upstream model ID
**Generated Output:**
The local CLIProxy config still writes the upstream dashed section name:
```yaml theme={null}
oauth-model-alias:
codex:
- name: gpt-5.6-sol
alias: gpt-5.6-sol-fast
fork: true
```
***
### `cliproxy.payload`
**Type:** Object
**Priority:** HIGH
**Purpose:** Store scoped request override rules for generated CLIProxy config
```yaml theme={null}
cliproxy:
payload:
default:
- models:
- name: keep-default
params:
temperature: 0.2
override:
- models:
- name: gpt-5.6-sol-fast
protocol: codex
params:
service_tier: priority
```
**Behavior:**
* `cliproxy.payload.override` is an ordered array of scoped override rules
* Each rule must define `models` and `params`
* Model selectors can include `name`, optional `protocol`, and any extra selector constraints supported by CLIProxy
* CCS preserves extra selector fields and extra payload subsections that are not part of the override list
* A configured override replaces an existing one only when the full predicate matches aside from `params`
* Distinct predicates remain distinct even if they target the same model
* Matching configured rules win over existing generated-config rules during regeneration
**Why This Matters:**
* Keeps manual payload sections intact while CCS refreshes generated config
* Lets a Codex-specific alias pair with `service_tier: priority` in a stable way
* Preserves extra match constraints instead of flattening them away
**Generated Output:**
The local CLIProxy config writes the upstream `payload` block and keeps the
match rule aligned with the alias:
```yaml theme={null}
payload:
override:
- models:
- name: gpt-5.6-sol-fast
protocol: codex
params:
service_tier: priority
```
***
## CLIProxy Server Configuration
### `cliproxy_server.fallback.enabled`
**Type:** Boolean
**Priority:** HIGH
**Purpose:** Enable fallback to local proxy if remote fails
```yaml theme={null}
cliproxy_server:
fallback:
enabled: true # Default: true
```
**Behavior:**
* `true`: Try local proxy if remote unreachable
* `false`: Fail with `PROXY_ERROR` if remote fails
**Use Cases:**
* Graceful degradation for network issues
* Offline work capability
* Testing without remote infrastructure
**Related:** `--remote-only` CLI flag
***
### `cliproxy_server.fallback.auto_start`
**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Auto-start local proxy on fallback
```yaml theme={null}
cliproxy_server:
fallback:
enabled: true
auto_start: false # Default: false
```
**Behavior:**
* `false`: Use existing local proxy only
* `true`: Spawn local proxy if not running
**Use Cases:**
* Seamless fallback without manual intervention
* Ensure proxy always available
***
### `cliproxy_server.remote.management_key`
**Type:** String
**Priority:** MEDIUM
**Purpose:** Separate management key for remote proxy
```yaml theme={null}
cliproxy_server:
remote:
enabled: true
host: "proxy.example.com"
auth_token: "api-token-123"
management_key: "mgmt-key-456" # Optional
```
**Behavior:**
* Used for management endpoints on remote proxy
* Falls back to `auth_token` if not specified
* Allows separate credentials for API vs management
**Security:** Use different keys for production environments
***
### `cliproxy_server.remote.timeout`
**Type:** Integer (milliseconds)
**Priority:** LOW
**Purpose:** Health check timeout for remote proxy
```yaml theme={null}
cliproxy_server:
remote:
enabled: true
host: "proxy.example.com"
timeout: 2000 # Milliseconds (defaults to 2000ms if not specified)
```
**Behavior:**
* Used for initial health check only
* Higher values for slow networks
* Does NOT affect API request timeouts
**Related:** `--proxy-timeout` CLI flag
***
## OpenAI-Compatible Local Proxy Configuration
Controls the local Anthropic-compatible proxy used when a Claude-target API
profile points at an OpenAI-compatible chat-completions endpoint.
### `proxy.port`
**Type:** Integer
**Priority:** MEDIUM
**Purpose:** Preferred shared local proxy port
```yaml theme={null}
proxy:
port: 45000
```
**Behavior:**
* Used as the preferred starting port for compatible profiles
* Legacy `3456` is treated as unset unless explicitly pinned at launch
* Overridden by `--port` and `proxy.profile_ports.`
***
### `proxy.profile_ports`
**Type:** Object
**Priority:** HIGH
**Purpose:** Exact per-profile local proxy port pins
```yaml theme={null}
proxy:
profile_ports:
hf: 3460
openrouter: 3461
```
**Behavior:**
* Lets multiple OpenAI-compatible profiles run at the same time
* `ccs proxy status ` and `ccs proxy activate ` report the
actual running port
***
### `proxy.routing`
**Type:** Object
**Priority:** MEDIUM
**Purpose:** Request-time routing for compatible proxy profiles
```yaml theme={null}
proxy:
routing:
default: "deepseek:deepseek-chat"
background: "ollama:qwen2.5-coder:0.5b"
think: "deepseek:deepseek-reasoner"
longContext: "openrouter:google/gemini-2.5-pro"
longContextThreshold: 60000
webSearch: "openrouter:perplexity/sonar-pro"
```
**Behavior:**
* Supports `profile:model`, `profile`, and exact model-id selectors
* Applies scenario routes for background, thinking, long-context, and web-search requests
* `longContextThreshold` uses an approximate token estimate
**Related:** [OpenAI-Compatible Provider Routing](/features/proxy/openai-compatible-providers)
***
## Browser Automation Configuration
Controls Claude Browser Attach and Codex Browser Tools.
```yaml theme={null}
browser:
claude:
enabled: false
policy: manual
user_data_dir: "~/.ccs/browser/chrome-user-data"
devtools_port: 9222
eval_mode: readonly
codex:
enabled: false
policy: manual
eval_mode: readonly
```
### `browser.claude`
**Type:** Object
**Priority:** HIGH
**Purpose:** Configure Claude Browser Attach
**Fields:**
* `enabled`: turn the Claude attach lane on or off
* `policy`: `manual` or `auto`
* `user_data_dir`: Chrome user-data directory for attach mode
* `devtools_port`: expected Chrome remote debugging port
* `eval_mode`: `disabled`, `readonly`, or `readwrite`
### `browser.codex`
**Type:** Object
**Priority:** HIGH
**Purpose:** Configure Codex Browser Tools
**Fields:**
* `enabled`: turn managed Codex browser tooling on or off
* `policy`: `manual` or `auto`
* `eval_mode`: `disabled`, `readonly`, or `readwrite`
**Behavior:**
* New installs default both lanes to disabled/manual
* `manual` hides browser tooling until a launch uses `--browser`
* `--no-browser` suppresses tooling even when policy is `auto`
**Related:** [Browser Automation](/features/workflow/browser-automation)
***
## Quota Management Configuration
### Supported Quota Providers
The following providers support quota tracking and rotation via `ccs cliproxy quota` and the `quota_management` section:
| Provider ID | Description |
| ----------- | ---------------------------------------------------------- |
| `agy` | Antigravity (multi-account) |
| `codex` | OpenAI Codex |
| `gemini` | Google Gemini |
| `claude` | Anthropic Claude OAuth (5-hour + weekly windows, failover) |
| `ghcp` | GitHub Copilot compatibility (deprecated) |
***
### `quota_management.mode`
**Type:** String (`auto` | `manual` | `hybrid`)
**Priority:** MEDIUM
**Purpose:** Account selection strategy for OAuth providers
```yaml theme={null}
quota_management:
mode: hybrid # Default: hybrid
```
**Behavior:**
* `auto`: CCS selects account based on quota/tier automatically
* `manual`: Only use paused/forced\_default settings
* `hybrid`: Auto-selection respects manual overrides (recommended)
***
### `quota_management.auto.preflight_check`
**Type:** Boolean
**Priority:** HIGH
**Purpose:** Check quota before starting Claude session
```yaml theme={null}
quota_management:
auto:
preflight_check: true # Default: true
```
**Behavior:**
* `true`: Check account quota before request, auto-switch if exhausted
* `false`: Skip pre-flight check, rely on 429 error handling
**Use Cases:**
* Prevent delays from exhausted accounts
* Smoother multi-account experience
***
### `quota_management.auto.exhaustion_threshold`
**Type:** Integer (0-100, percentage)
**Priority:** LOW
**Purpose:** Quota % below which account is "exhausted"
```yaml theme={null}
quota_management:
auto:
exhaustion_threshold: 5 # Default: 5%
```
**Behavior:**
* Accounts below threshold are skipped in rotation
* Prevents using nearly-exhausted accounts
***
### `quota_management.auto.tier_priority`
**Type:** Array of strings
**Priority:** LOW
**Purpose:** Account tier preference order
```yaml theme={null}
quota_management:
auto:
tier_priority: ["ultra", "pro", "free"] # Default: ["ultra", "pro", "free"]
```
**Behavior:**
* Accounts sorted by tier priority, then by quota %
* Tiers not in list get lowest priority
**Available Tiers:**
* `ultra` - Ultra subscription accounts
* `pro` - Pro subscription accounts
* `free` - Free tier accounts
***
### `quota_management.auto.cooldown_minutes`
**Type:** Integer (minutes)
**Priority:** LOW
**Purpose:** Skip exhausted accounts for N minutes
```yaml theme={null}
quota_management:
auto:
cooldown_minutes: 5 # Default: 5
```
**Behavior:**
* Exhausted accounts are skipped for cooldown period
* Prevents repeated failed attempts on same account
***
### `quota_management.manual.paused_accounts`
**Type:** Array of strings
**Priority:** HIGH
**Purpose:** Accounts to skip in rotation
```yaml theme={null}
quota_management:
manual:
paused_accounts: [] # Default: []
```
**Behavior:**
* Listed accounts are never selected automatically
* Set via `ccs cliproxy pause `
* Remove via `ccs cliproxy resume `
***
### `quota_management.manual.forced_default`
**Type:** String | null
**Priority:** HIGH
**Purpose:** Force specific account for all requests
```yaml theme={null}
quota_management:
manual:
forced_default: null # Default: null
```
**Behavior:**
* `null`: Normal account rotation
* ``: Always use this account
**Use Cases:**
* Testing specific account
* Temporarily override rotation
***
### `quota_management.manual.tier_lock`
**Type:** String | null
**Priority:** MEDIUM
**Purpose:** Only use accounts of specific tier
```yaml theme={null}
quota_management:
manual:
tier_lock: null # Default: null
```
**Behavior:**
* `null`: Use all tiers
* `paid`: Only paid accounts
* `free`: Only free accounts
***
## Global Environment Variables
### `global_env.enabled`
**Type:** Boolean
**Priority:** MEDIUM
**Purpose:** Enable global env var injection
```yaml theme={null}
global_env:
enabled: true # Default: true
```
**Behavior:**
* `true`: Inject `global_env.env` into all non-Claude profiles
* `false`: Disable feature
**Use Cases:**
* Disable Claude Code telemetry for proxy providers
* Set common env vars across all profiles
***
### `global_env.env`
**Type:** Object (key-value pairs)
**Priority:** MEDIUM
**Purpose:** Environment variables for all non-Claude profiles
```yaml theme={null}
global_env:
enabled: true
env:
DISABLE_BUG_COMMAND: "1"
DISABLE_ERROR_REPORTING: "1"
DISABLE_TELEMETRY: "1"
```
**Behavior:**
* Applied to settings-based and CLIProxy profiles
* NOT applied to native Claude or account-based profiles
* Merged with profile-specific env vars
**Default Values:**
* `DISABLE_BUG_COMMAND: "1"`
* `DISABLE_ERROR_REPORTING: "1"`
* `DISABLE_TELEMETRY: "1"`
**Use Cases:**
* Disable Claude Code telemetry globally
* Set API base URLs
* Configure logging levels
***
## WebSearch Configuration
### `websearch.providers.gemini.model`
**Type:** String
**Priority:** LOW
**Purpose:** Gemini model for WebSearch feature
```yaml theme={null}
websearch:
providers:
gemini:
enabled: true
model: "gemini-2.5-flash" # Default
timeout: 55
```
**Behavior:**
* Used by WebSearch hook for third-party profiles
* Free tier: 1000 requests/day
* Falls back to OpenCode/Grok if fails
**Available Models:**
* `gemini-2.5-flash` (default, fastest)
* `gemini-2.5-pro` (more accurate)
***
### `websearch.providers.gemini.timeout`
**Type:** Integer (seconds)
**Priority:** LOW
**Purpose:** Gemini CLI timeout for WebSearch
```yaml theme={null}
websearch:
providers:
gemini:
timeout: 55 # Default: 55 seconds
```
**Behavior:**
* Max time for single WebSearch request
* Prevents hanging on slow responses
* Falls back to next provider on timeout
***
### `websearch.providers.opencode`
**Type:** Object
**Priority:** LOW
**Purpose:** OpenCode provider configuration
```yaml theme={null}
websearch:
providers:
opencode:
enabled: false # Default: false
model: "opencode/grok-code"
timeout: 90
```
**Behavior:**
* Free provider via Zen platform
* Requires OpenCode CLI installed
* Fallback option after Gemini
**Activation:**
* Set `enabled: true`
* Install: `npm install -g opencode`
***
### `websearch.providers.grok`
**Type:** Object
**Priority:** LOW
**Purpose:** Grok CLI provider configuration
```yaml theme={null}
websearch:
providers:
grok:
enabled: false # Default: false
timeout: 55
```
**Behavior:**
* Requires `GROK_API_KEY` environment variable
* Paid API, better quality than free providers
* Last fallback option
**Activation:**
* Set `enabled: true`
* Set `GROK_API_KEY` env var
* Install: `npm install -g @vibe-kit/grok-cli`
***
## Copilot Configuration (Deprecated)
Copilot configuration remains available for existing compatibility setups. New
provider setup should prefer Codex or another active provider.
### `copilot.account_type`
**Type:** String (`individual` | `business` | `enterprise`)
**Priority:** LOW
**Purpose:** GitHub Copilot subscription type
```yaml theme={null}
copilot:
enabled: false
account_type: individual # Default: individual
```
**Behavior:**
* `individual`: Personal subscription
* `business`: Enterprise/team subscription
* `enterprise`: Enterprise subscription
**Use Cases:**
* Billing/usage tracking
* Feature access control
***
### `copilot.rate_limit`
**Type:** Integer | null
**Priority:** LOW
**Purpose:** Rate limiting for Copilot API
```yaml theme={null}
copilot:
rate_limit: null # Default: null (no limit)
```
**Behavior:**
* `null`: No rate limiting
* Integer: Seconds between requests
**Use Cases:**
* Prevent API abuse
* Control costs for business accounts
***
### `copilot.wait_on_limit`
**Type:** Boolean
**Priority:** LOW
**Purpose:** Wait vs fail on rate limit
```yaml theme={null}
copilot:
rate_limit: 60
wait_on_limit: true # Default: true
```
**Behavior:**
* `true`: Wait until rate limit window resets
* `false`: Fail with error immediately
***
## Configuration Patterns
### Priority Resolution
CCS resolves configuration values in this order:
1. **CLI Flags** (highest priority)
2. **Environment Variables**
3. **config.yaml**
4. **Defaults** (lowest priority)
**Example:**
```bash theme={null}
# All three set the same value
ccs codex --proxy-host proxy.example.com # CLI flag
CCS_PROXY_HOST=proxy.example.com ccs codex # Env var
# config.yaml: cliproxy_server.remote.host: proxy.example.com
```
**Result:** CLI flag wins, then env var, then config file
***
### Variant Isolation Pattern
Run multiple variants concurrently without conflicts:
```yaml theme={null}
cliproxy:
variants:
codex-dev:
provider: codex
port: 8318
auth:
api_key: "dev-key"
management_secret: "dev-secret"
codex-prod:
provider: codex
port: 8319
auth:
api_key: "prod-key"
management_secret: "prod-secret"
```
**Usage:**
```bash theme={null}
ccs codex-dev # Port 8318, dev credentials
ccs codex-prod # Port 8319, prod credentials
```
***
### Remote Proxy with Fallback Pattern
Graceful degradation for network issues:
```yaml theme={null}
cliproxy_server:
remote:
enabled: true
host: "proxy.example.com"
port: 8443
protocol: "https"
auth_token: "remote-token"
timeout: 5000
fallback:
enabled: true
auto_start: true
local:
port: 8317
auto_start: true
```
**Behavior:**
1. Try remote proxy at `https://proxy.example.com:8443`
2. If unreachable after 5s, fall back to local proxy
3. Auto-start local proxy if not running
4. Use local proxy on port 8317
***
## Thinking Configuration
Controls thinking/reasoning budget injection for CLIProxy providers.
### `thinking.mode`
**Type:** String (`auto` | `off` | `manual`)
**Priority:** HIGH
**Purpose:** Thinking mode control
```yaml theme={null}
thinking:
mode: auto # Default: auto
```
**Behavior:**
* `auto`: Apply tier-based defaults (opus→high, sonnet→medium, haiku→low)
* `off`: Disable thinking entirely
* `manual`: Use explicit override value
***
### `thinking.override`
**Type:** String | Integer
**Priority:** MEDIUM
**Purpose:** Manual override value for thinking budget
```yaml theme={null}
thinking:
mode: manual
override: "high" # Or numeric budget value
```
**Behavior:**
* Used when `mode: manual`
* Can be level name (e.g., "high", "medium", "low") or numeric budget
* Applies to all providers unless overridden
***
### `thinking.tier_defaults`
**Type:** Object
**Priority:** LOW
**Purpose:** Tier-to-thinking level mapping
```yaml theme={null}
thinking:
tier_defaults:
opus: "high" # Default
sonnet: "medium" # Default
haiku: "low" # Default
```
**Behavior:**
* Maps Claude tier names to thinking level names
* Used when `mode: auto`
* Customizable per tier
***
### `thinking.provider_overrides`
**Type:** Object
**Priority:** LOW
**Purpose:** Per-provider tier defaults
```yaml theme={null}
thinking:
provider_overrides:
gemini:
opus: "high"
sonnet: "medium"
```
**Behavior:**
* Overrides global tier defaults for specific providers
* Useful for provider-specific configurations
***
### `thinking.show_warnings`
**Type:** Boolean
**Priority:** LOW
**Purpose:** Show warnings when values are clamped
```yaml theme={null}
thinking:
show_warnings: true # Default: true
```
**Behavior:**
* `true`: Show warning when budget values are adjusted
* `false`: Silent clamping
***
## Official Channels Configuration
Controls runtime-only auto-enable for Anthropic's official Claude channels.
### `channels.selected`
**Type:** Array of strings
**Priority:** HIGH
**Purpose:** Select which official channel plugins CCS auto-adds at launch
```yaml theme={null}
channels:
selected: [] # Default: []
```
**Behavior:**
* Accepted values: `telegram`, `discord`, `imessage`
* `all` is accepted by the CLI helper, but config.yaml stores the explicit array
* CCS adds `--channels` with every selected ready official plugin at runtime
* Applies only to native Claude `default` and `account` sessions
* Ignored for API-key profiles, CLIProxy, Copilot, Cursor proxy, and Droid target flows
* iMessage is macOS-only
* Telegram and Discord use Claude channel env files for bot tokens
Claude bot tokens are not stored in `config.yaml`. CCS writes them to Claude's
official channel env files: `~/.claude/channels/telegram/.env` as
`TELEGRAM_BOT_TOKEN` and `~/.claude/channels/discord/.env` as
`DISCORD_BOT_TOKEN`.
***
### `channels.unattended`
**Type:** Boolean
**Priority:** HIGH
**Purpose:** Also add runtime `--dangerously-skip-permissions`
```yaml theme={null}
channels:
unattended: false # Default: false
```
**Behavior:**
* `true`: Adds `--dangerously-skip-permissions` only when at least one selected official channel is auto-enabled
* `false`: Leaves permission mode unchanged
* Explicit user permission flags override this default
This is runtime-only and high risk. CCS does not persist bypass permissions
into Claude settings.
***
## Image Analysis Configuration
Controls MCP-first image/PDF analysis for third-party launches.
### `image_analysis.enabled`
**Type:** Boolean
**Priority:** HIGH
**Purpose:** Enable image analysis via CLIProxy
```yaml theme={null}
image_analysis:
enabled: true # Default: true
```
**Behavior:**
* `true`: Expose the managed `ImageAnalysis` path when the runtime is healthy
* `false`: Disable image analysis
***
### `image_analysis.timeout`
**Type:** Integer (seconds)
**Priority:** LOW
**Purpose:** Timeout for vision analysis requests
```yaml theme={null}
image_analysis:
timeout: 60 # Default: 60
```
**Behavior:**
* Max time for single vision analysis request
* Prevents hanging on slow responses
***
### `image_analysis.provider_models`
**Type:** Object
**Priority:** MEDIUM
**Purpose:** Provider-to-model mapping for vision analysis
```yaml theme={null}
image_analysis:
provider_models:
agy: "gemini-2.5-flash"
gemini: "gemini-2.5-flash"
codex: "gpt-5.1-codex-mini"
kiro: "kiro-claude-haiku-4-5"
ghcp: "claude-haiku-4.5"
claude: "claude-haiku-4-5-20251001"
kimi: "kimi-k2.5"
```
**Behavior:**
* Maps provider names to vision model IDs
* Customizable per provider
* Defaults provided for all supported providers
***
### `image_analysis.fallback_backend`
**Type:** String
**Priority:** MEDIUM
**Purpose:** Default backend for bridge-backed profiles that need image analysis
```yaml theme={null}
image_analysis:
fallback_backend: gemini
```
***
### `image_analysis.profile_backends`
**Type:** Object
**Priority:** MEDIUM
**Purpose:** Override the resolved image-analysis backend for specific settings profiles
```yaml theme={null}
image_analysis:
profile_backends:
glm: agy
```
***
## Dashboard Authentication
Optional username/password protection for the CCS dashboard.
See [Dashboard Authentication](/features/dashboard/auth) for full setup guide.
### `dashboard_auth.enabled`
**Type:** Boolean
**Priority:** HIGH
**Purpose:** Enable dashboard login requirement
```yaml theme={null}
dashboard_auth:
enabled: false # Default: false
```
**Behavior:**
* `false`: Dashboard accessible without login (default)
* `true`: Requires username/password to access dashboard
***
### `dashboard_auth.username`
**Type:** String
**Priority:** HIGH
**Purpose:** Login username
```yaml theme={null}
dashboard_auth:
username: "admin"
```
***
### `dashboard_auth.password_hash`
**Type:** String (bcrypt hash)
**Priority:** HIGH
**Purpose:** Bcrypt-hashed password
```yaml theme={null}
dashboard_auth:
password_hash: "$2b$10$..."
```
**Generate hash:**
```bash theme={null}
npx bcrypt-cli hash 'your-password'
```
Never store plain-text passwords. Always use bcrypt hash.
***
### `dashboard_auth.session_timeout_hours`
**Type:** Integer
**Priority:** LOW
**Purpose:** Session duration before re-login required
```yaml theme={null}
dashboard_auth:
session_timeout_hours: 24 # Default: 24
```
***
### Dashboard Auth Environment Variables
| Variable | Maps To |
| ----------------------------- | ------------------------------ |
| `CCS_DASHBOARD_AUTH_ENABLED` | `dashboard_auth.enabled` |
| `CCS_DASHBOARD_USERNAME` | `dashboard_auth.username` |
| `CCS_DASHBOARD_PASSWORD_HASH` | `dashboard_auth.password_hash` |
| `CCS_SESSION_SECRET` | Custom session encryption key |
Environment variables override config.yaml values.
***
## Continuity Configuration
Available since v9 (CCS v7.51.0)
Cross-profile continuity inheritance lets API profiles and CLIProxy variant profiles reuse an account profile's workspace context (`CLAUDE_CONFIG_DIR`). This shares conversation history, project files, and session state across profiles, which means the inherited profile is no longer isolated from that source account lane.
### `continuity.inherit_from_account`
**Type:** Object (map of profile names to account names)
**Priority:** MEDIUM
**Purpose:** Inherit workspace continuity from an account profile
```yaml theme={null}
continuity:
inherit_from_account:
glm: pro # GLM profile inherits from "pro" account
albb: work # albb profile inherits from "work" account
gemini-dev: dev # gemini-dev variant inherits from "dev" account
```
**Behavior:**
* Maps a non-account profile name to an account profile name
* When the mapped profile runs with `target: claude`, it uses the account's `CLAUDE_CONFIG_DIR`
* Conversation history, project state, and sessions are shared with that account profile
* The inherited profile and source account now reuse the same underlying Claude config directory
* Only applies when `target='claude'` — has no effect on `target: droid` profiles
* Never applies to account profiles themselves
**Supported profile types:**
* Settings-based profiles (`profiles.`)
* CLIProxy variant profiles (`cliproxy.variants.`)
* Built-in API presets (glm, albb, etc.)
**Not supported for:**
* Account profiles (type: account)
* Copilot profiles
**Example use case — share session context between Claude and GLM:**
```yaml theme={null}
# config.yaml
continuity:
inherit_from_account:
glm: pro # GLM reuses the "pro" account's Claude config dir
# Now running "ccs glm" will:
# 1. Load GLM's API endpoint and key
# 2. Set CLAUDE_CONFIG_DIR to the "pro" account's instance path
# 3. Access same project files/conversations as "ccs pro"
```
**Legacy support:** The root-level `continuity_inherit_from_account` key in `config.json` is still supported for backward compatibility but deprecated. Migrate to `continuity.inherit_from_account` in `config.yaml`.
***
## Migration from v12 to v13
Version 13 adds OpenAI-compatible local proxy settings and browser automation
settings. Migration is automatic.
**Changes:**
* Added `proxy` section for local compatible-provider proxy ports and routing
* Added `browser` section for Claude Browser Attach and Codex Browser Tools
* New installs default browser lanes to disabled/manual
**Required Action:** None. Run `ccs doctor --fix` if you want CCS to rewrite the
current config file with the latest commented template.
***
## Migration from v8 to v9
Version 9 adds cross-profile continuity inheritance. Migration is automatic.
**Changes:**
* Added `continuity` section with `inherit_from_account` mapping
* Config version bumped from 8 to 9
**Action Required:**
* None (automatic migration with empty defaults)
* Optional: Configure `continuity.inherit_from_account` to share workspace context between profiles
***
## Migration from v7 to v8
Version 8 adds thinking/reasoning budget and image analysis configuration. Migration is automatic.
**Changes:**
* Added `thinking` section for reasoning budget control
* Added `image_analysis` section for vision model configuration
* Updated config version from 7 to 8
**Action Required:**
* None (automatic migration with defaults)
* Optional: Customize thinking levels or vision models
***
## Migration from v6 to v7
Version 7 adds quota management for hybrid auto+manual account control. Migration is automatic.
**Changes:**
* Added `quota_management` section
* Added tier-based quota prioritization
* Added manual account controls (pause/force/tier-lock)
**Action Required:**
* None (automatic migration with defaults)
* Optional: Configure quota management preferences
***
## Migration from v5 to v6
Version 6 adds customizable auth tokens. Migration is automatic.
**Changes:**
* Added `cliproxy.auth.api_key` (default: `"ccs-internal-managed"`)
* Added `cliproxy.auth.management_secret` (default: `"ccs"`)
* Added `cliproxy.variants..auth` for per-variant override
* Added `cliproxy_server.remote.management_key` for separate management auth
**Action Required:**
* None (automatic migration with defaults)
* Optional: Customize auth keys for enhanced security
***
## Validation Rules
CCS validates configuration on load. Common errors:
**Schema Errors:**
* `version` must be integer >= 1
* Ports must be 1-65535
* Boolean fields reject non-boolean values
**Semantic Errors:**
* Variant names must not conflict with built-in providers
* Profile names cannot be reserved words
* Email addresses must be valid format
* Hostnames must be valid DNS/IP
**Recovery:**
* Run `ccs doctor --fix` for auto-repair
* Run `ccs migrate` for version upgrades
* Delete corrupt config and run `ccs setup`
***
## Docker Deployment Configuration
Auto-generated section written by `ccs docker up`. Stores paths and defaults for the Docker deployment stack.
### `docker.compose_file`
**Type:** String (file path)
**Priority:** LOW
**Purpose:** Path to the generated Docker Compose file
```yaml theme={null}
docker:
compose_file: "~/.ccs/docker/docker-compose.yml"
```
**Behavior:**
* Auto-written by `ccs docker up`
* Points to the bundled compose file in `~/.ccs/docker/`
* Override only if using a custom compose setup
***
### `docker.host`
**Type:** String | null
**Priority:** MEDIUM
**Purpose:** Default SSH target for remote Docker operations
```yaml theme={null}
docker:
host: "user@myserver.com" # or null for local
```
**Behavior:**
* `null`: All `ccs docker` commands target localhost
* `"user@host"`: All `ccs docker` commands default to remote target
* Overridden by `--host` CLI flag per-command
***
### Full Docker Section Example
```yaml theme={null}
docker:
compose_file: "~/.ccs/docker/docker-compose.yml"
host: null # null = local, or "user@host" for remote default
```
The `docker` section is auto-generated by `ccs docker up` or `ccs docker
config`. Manual editing is rarely needed.
***
## Related Resources
* [CLI Flags Reference](/reference/cli-flags)
* [CLI Commands Reference](/reference/cli-commands)
* [Error Codes](/reference/error-codes)
* [Migration Guide](/reference/migration-v6-v7)
# Error Codes Reference
Source: https://docs.ccs.kaitran.ca/reference/error-codes
Reference for CCS runtime E### error IDs, categories, and recovery guidance.
# Error Codes Reference
CCS prints `E###` runtime error IDs in stderr output. Each link emitted by the CLI points to this page with a lowercase anchor such as `/reference/error-codes#e104`.
> Numeric process exit codes such as `0`, `1`, and `130` are documented in [CLI Commands](/reference/cli-commands#exit-codes). This page is only for runtime `E###` IDs.
## Quick Lookup
| Code | Identifier | Category | Meaning |
| ------ | ------------------------------- | -------------------- | --------------------------------------------------------------------- |
| `E101` | `CONFIG_MISSING` | Configuration | Required CCS configuration is missing. |
| `E102` | `CONFIG_INVALID_JSON` | Configuration | Stored config content could not be parsed. |
| `E103` | `CONFIG_INVALID_PROFILE` | Configuration | Profile configuration is missing or invalid. |
| `E104` | `PROFILE_NOT_FOUND` | Profile Management | Requested profile does not exist. |
| `E105` | `PROFILE_ALREADY_EXISTS` | Profile Management | Profile creation conflicted with an existing name. |
| `E106` | `PROFILE_CANNOT_DELETE_DEFAULT` | Profile Management | The default profile cannot be removed. |
| `E107` | `PROFILE_INVALID_NAME` | Profile Management | Profile name failed validation. |
| `E301` | `CLAUDE_NOT_FOUND` | Claude CLI Detection | Claude CLI binary was not found. |
| `E302` | `CLAUDE_VERSION_INCOMPATIBLE` | Claude CLI Detection | Installed Claude CLI version is unsupported. |
| `E303` | `CLAUDE_EXECUTION_FAILED` | Claude CLI Detection | Claude CLI launch or execution failed. |
| `E401` | `GLMT_PROXY_TIMEOUT` | Network/API | Historical legacy GLMT proxy timeout code retained for compatibility. |
| `E402` | `API_KEY_MISSING` | Network/API | Required API key is missing. |
| `E403` | `API_AUTH_FAILED` | Network/API | Upstream API authentication was rejected. |
| `E404` | `API_RATE_LIMIT` | Network/API | Upstream API rate limit was reached. |
| `E501` | `FS_CANNOT_CREATE_DIR` | File System | CCS could not create a required directory. |
| `E502` | `FS_CANNOT_WRITE_FILE` | File System | CCS could not write a required file. |
| `E503` | `FS_CANNOT_READ_FILE` | File System | CCS could not read a required file. |
| `E504` | `FS_INSTANCE_NOT_FOUND` | File System | Expected instance directory or file was not found. |
| `E900` | `INTERNAL_ERROR` | Internal | Unexpected internal failure. |
| `E901` | `INVALID_STATE` | Internal | Code reached an invalid or impossible state. |
## Configuration Errors
E101: CONFIG\_MISSING
Required CCS configuration or a required config value is missing.
E102: CONFIG\_INVALID\_JSON
Persisted config content exists but cannot be parsed.
E103: CONFIG\_INVALID\_PROFILE
The requested profile config is missing, unreadable, or structurally invalid.
## Profile Management Errors
These profile-management codes intentionally remain in the `E104-E107` range for compatibility with the current CLI output.
E104: PROFILE\_NOT\_FOUND
Raised when CCS is asked to run or inspect a profile name that is not registered.
E105: PROFILE\_ALREADY\_EXISTS
Raised when profile creation would overwrite an existing profile name.
E106: PROFILE\_CANNOT\_DELETE\_DEFAULT
Raised when a command tries to remove the default profile.
E107: PROFILE\_INVALID\_NAME
Raised when a supplied profile name does not meet CCS validation rules.
## Claude CLI Detection Errors
E301: CLAUDE\_NOT\_FOUND
Claude CLI is not available in `PATH` or at the configured override path.
E302: CLAUDE\_VERSION\_INCOMPATIBLE
Claude CLI was found, but the installed version is outside the supported range.
E303: CLAUDE\_EXECUTION\_FAILED
Claude CLI started or was invoked, but the execution failed unexpectedly.
## Network/API Errors
E401: GLMT\_PROXY\_TIMEOUT
Legacy `ccs glmt` proxy communication or the related auth flow exceeded the
allowed timeout. This is a historical compatibility code. Current `ccs glmt`
flows are normalized to direct GLM settings at runtime, so migrate to `ccs glm`
or `ccs km` for supported API workflows when possible.
E402: API\_KEY\_MISSING
An API-backed profile is missing a required key or token.
E403: API\_AUTH\_FAILED
Authentication failed against the upstream provider or proxy.
E404: API\_RATE\_LIMIT
The upstream provider refused the request because rate limits were exceeded.
## File System Errors
E501: FS\_CANNOT\_CREATE\_DIR
CCS failed to create a directory it needs for config, auth, or instance state.
E502: FS\_CANNOT\_WRITE\_FILE
CCS failed to write a required file, usually because of permissions or path issues.
E503: FS\_CANNOT\_READ\_FILE
CCS failed to read a required file from disk.
E504: FS\_INSTANCE\_NOT\_FOUND
The expected isolated instance path or related on-disk state does not exist.
## Internal Errors
E900: INTERNAL\_ERROR
Fallback code for unexpected internal failures that do not fit a more specific category.
E901: INVALID\_STATE
Raised when execution reaches a state the code considers invalid or unreachable.
## Related References
* [CLI Commands](/reference/cli-commands#exit-codes)
* [CLI Flags](/reference/cli-flags)
* [Troubleshooting](/reference/troubleshooting)
# File Locations
Source: https://docs.ccs.kaitran.ca/reference/file-locations
Complete filesystem structure for CCS configuration, credentials, and data
# File Locations
Reference for CCS configuration, credentials, cache, logs, and runtime paths. **Base Directory:** `~/.ccs/` (override with `CCS_DIR`, or legacy `CCS_HOME` which appends `.ccs`)
## Overview
```
~/.ccs/
├── config.yaml # Main config (v13 schema)
├── profiles.json # Profile registry (legacy, deprecated)
├── instances/ # Account instances (isolated Claude dirs)
│ ├── work/
│ └── personal/
├── cliproxy/
│ ├── auth/ # OAuth tokens (per provider)
│ │ └── xai-*.json # xAI OAuth tokens
│ ├── config.yaml # CLIProxy config (auto-generated)
│ ├── sessions.json # Active sessions (global)
│ ├── accounts.json # Provider account registry
│ └── bin/
│ ├── original/ # CLIProxyAPI binary + version.txt
│ └── plus/ # CLIProxyAPIPlus binary + version.txt
├── model-catalog-cache.json # Cached remote model catalog snapshot
├── shared/
│ ├── commands/ # Custom commands (symlinked to instances)
│ ├── skills/ # Custom skills (symlinked)
│ ├── agents/ # Custom agents (symlinked)
│ ├── settings.json # Link to canonical Claude settings
│ └── CLAUDE.md # Link to canonical user instructions
├── docker/ # Docker deployment assets (auto-generated)
├── logs/
│ ├── current.jsonl # CCS-owned structured log stream
│ └── archive/ # Rotated structured log segments
├── xai.settings.json # xAI provider settings when used
└── *.settings.json # API profile settings files
~/.claude/
├── settings.json # Canonical Claude Code settings
├── CLAUDE.md # Canonical shared user instructions
└── channels/
├── telegram/.env # TELEGRAM_BOT_TOKEN
└── discord/.env # DISCORD_BOT_TOKEN
```
Path precedence is `--config-dir` → `CCS_DIR` → legacy `CCS_HOME/.ccs` →
default `~/.ccs/`.
***
## Configuration Files
### `~/.ccs/config.yaml`
**Purpose:** Main unified configuration file (v13)
**Format:** YAML
**Created:** First run, or via `ccs setup`
**Delete:** Only if resetting CCS completely
**Contains:**
* Default profile setting
* Account-based profiles
* API-based profiles
* CLIProxy configuration
* User preferences
* WebSearch settings
* Global environment variables
* Quota management (v7+)
* Thinking configuration (v8+)
* Dashboard authentication
* Image analysis configuration (v8+)
* Deprecated Copilot compatibility settings
* Remote/local proxy configuration
* OpenAI-compatible local proxy configuration (v13+)
* Browser automation configuration (v13+)
**Example:**
```yaml theme={null}
version: 13
default: work
accounts:
work:
created: "2025-12-01T10:00:00Z"
last_used: "2025-12-15T14:30:00Z"
profiles:
glm:
type: "api"
settings: "~/.ccs/glm.settings.json"
cliproxy:
oauth_accounts:
kai-personal: "kai@example.com"
variants:
my-gemini:
provider: gemini
port: 8318
proxy:
profile_ports:
hf: 3460
browser:
claude:
enabled: false
policy: manual
user_data_dir: "~/.ccs/browser/chrome-user-data"
devtools_port: 9222
codex:
enabled: false
policy: manual
```
**Related:**
* [Configuration Schema](/reference/config-schema)
* [Migration Guide](/reference/migration-v6-v7)
***
### `~/.ccs/*.settings.json`
**Purpose:** Profile-specific environment variables
**Format:** JSON
**Created:** Via `ccs api create ` or dashboard
**Delete:** Safe to delete (profile becomes unusable)
**Naming Pattern:** `~/.ccs/.settings.json`
**Contains:**
```json theme={null}
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.example.com/anthropic",
"ANTHROPIC_AUTH_TOKEN": "your-api-key",
"ANTHROPIC_MODEL": "model-name"
}
}
```
**Security:** Store securely, do not commit to version control
**Examples:**
* `~/.ccs/glm.settings.json` - GLM profile
* `~/.ccs/km.settings.json` - Kimi for Coding profile
* `~/.ccs/xai.settings.json` - xAI (Grok) provider settings
* `~/.ccs/custom-api.settings.json` - Custom API profile
`grok` is an xAI CLI alias; it does not create `grok.settings.json`.
***
## CLIProxy Files
### `~/.ccs/cliproxy/auth/xai-*.json`
**Purpose:** xAI OAuth credentials
**Created:** `ccs xai --auth` or `ccs grok --auth`
The token JSON uses `"type": "xai"`. Email metadata can be absent, so CCS
uses an email when present or derives the account ID from the token filename
suffix. The account registry stores xAI metadata at `providers.xai` in
`accounts.json`; `grok` does not create separate token files or a registry
bucket.
***
### `~/.ccs/cliproxy/sessions.json`
**Purpose:** Global session tracking for CLIProxy
**Format:** JSON
**Created:** First CLIProxy session
**Delete:** Safe (sessions will reset)
**Structure:**
```json theme={null}
{
"gemini": {
"activeCount": 2,
"sessions": [
{
"id": "sess-123",
"pid": 12345,
"started": "2025-12-15T10:00:00Z"
}
]
}
}
```
**Use Cases:**
* Track concurrent sessions per provider
* Prevent proxy shutdown with active sessions
* Debug session leaks
**Related:** `~/.ccs/cliproxy/sessions-{port}.json` for port-isolated variants
***
### `~/.ccs/cliproxy/sessions-{port}.json`
**Purpose:** Port-specific session tracking for variants
**Format:** JSON
**Created:** First session on variant with custom port
**Delete:** Safe (variant sessions will reset)
**Naming Pattern:** `~/.ccs/cliproxy/sessions-8318.json`
**Structure:**
```json theme={null}
{
"my-gemini": {
"activeCount": 1,
"sessions": [...]
}
}
```
**When Created:**
* Variant has `port` specified in `config.yaml`
* Port range: 8318-8417
**Related:**
* [Port Isolation Pattern](/reference/config-schema#variant-isolation-pattern)
* `cliproxy.variants..port` config key
***
### `~/.ccs/cliproxy/accounts.json`
**Purpose:** OAuth account registry for CLIProxy providers
**Format:** JSON
**Created:** First OAuth authentication
**Delete:** Removes all OAuth accounts (requires re-auth)
**Structure:**
```json theme={null}
{
"version": 1,
"providers": {
"xai": {
"default": "subject-one",
"accounts": {
"subject-one": {
"nickname": "personal",
"tokenFile": "xai-subject-one.json",
"createdAt": "2025-12-01T10:00:00Z"
}
}
}
}
}
```
**Operations:**
* Add account: `ccs codex --auth --add`
* List accounts: `ccs codex --accounts`
* Switch account: `ccs codex --use `
* Rename account: `ccs codex --nickname `
**Related:**
* [Multi-Account Guide](/providers/concepts/overview#multi-account)
* `cliproxy.oauth_accounts` config key
***
### `~/.ccs/cliproxy/config-{port}.yaml`
**Purpose:** Port-specific CLIProxy configuration
**Format:** YAML
**Created:** Automatically for variants with custom ports
**Delete:** Safe (will regenerate on next use)
**Naming Pattern:** `~/.ccs/cliproxy/config-8318.yaml`
**Contains:**
* Provider-specific settings
* Port configuration
* Auth credentials (if variant-specific)
* Logging settings
**When Created:**
* Variant has `port: 8318` in `config.yaml`
* Allows concurrent variants without config conflicts
**Related:**
* [Variant Isolation](/reference/config-schema#variant-isolation-pattern)
* Port range: 8318-8417
***
### `~/.ccs/cliproxy/bin/original/`
**Purpose:** CLIProxyAPI (original) binary directory
**Format:** Directory containing executable + version file
**Created:** During CLIProxy installation (`backend: original`)
**Delete:** Safe (will reinstall on next use)
**Files:**
* `cli-proxy-api` — CLIProxyAPI binary
* `version.txt` — Installed version string
**Use Cases:**
* Standard providers: gemini, codex, xai, agy, iflow, kimi, claude
* Minimal install without the plus-only provider set
***
### `~/.ccs/cliproxy/bin/plus/`
**Purpose:** CLIProxyAPIPlus binary directory
**Format:** Directory containing executable + version file
**Created:** During CLIProxy installation (`backend: plus`)
**Delete:** Safe (will reinstall on next use)
**Files:**
* `cli-proxy-api-plus` — CLIProxyAPIPlus binary
* `version.txt` — Installed version string
**Use Cases:**
* Plus-only providers including Kiro, Cursor, GitLab Duo, CodeBuddy, Kilo AI, Qoder, and deprecated GitHub Copilot compatibility
* Opt-in backend; `original` remains the default local backend
* Legacy deleted-upstream Plus installs migrate safely to the original backend
**Related Commands:**
* `ccs cliproxy` - Show current version
* `ccs cliproxy --install ` - Install specific version
* `ccs cliproxy --latest` - Update to latest
***
### `~/.ccs/model-catalog-cache.json`
**Purpose:** Cached model catalog snapshot from CLIProxy management sync
**Format:** JSON
**Created:** Via `ccs cliproxy catalog refresh`
**Delete:** Safe (reverts to static catalog; regenerates on next refresh)
**TTL:** 24 hours
**Contains:**
* Model IDs and metadata per provider
* Remote-overridden fields merged with static fallback
* Last-synced timestamp
**Related Commands:**
* `ccs cliproxy catalog` - View cache status
* `ccs cliproxy catalog refresh` - Force refresh
* `ccs cliproxy catalog reset` - Clear cache (revert to static)
***
### `~/.ccs/browser/chrome-user-data/`
**Purpose:** Recommended dedicated Chrome user-data directory for Claude Browser Attach
**Format:** Browser profile directory
**Created:** Via `ccs browser setup` or first managed setup path
**Delete:** Safe if you want to reset browser automation state
**Use Cases:**
* Keeps automation browser state separate from your daily browser profile
* Works with Chrome launched via `--remote-debugging-port=9222`
***
### `~/.ccs/mcp/ccs-browser-server.cjs`
**Purpose:** Managed local MCP runtime for Claude Browser Attach
**Format:** JavaScript runtime file
**Created:** When CCS prepares browser automation tooling
**Delete:** Safe; CCS recreates it when browser tooling is prepared again
**Related Commands:**
* `ccs browser setup`
* `ccs browser status`
* `ccs browser doctor`
***
## Claude Channel Token Files
### `~/.claude/channels/telegram/.env`
**Purpose:** Telegram bot token for Official Channels integration
**Format:** `.env` file with `TELEGRAM_BOT_TOKEN=`
**Created:** Via `ccs config channels --set-token telegram=`
**Delete:** Disables Telegram channel auto-enable
**Content:**
```
TELEGRAM_BOT_TOKEN=1234567890:AABBccDDeeFFggHH...
```
**Related:**
* [Official Channels](/reference/cli-commands#official-channels-configuration)
* `channels.selected` config key
***
### `~/.claude/channels/discord/.env`
**Purpose:** Discord bot token for Official Channels integration
**Format:** `.env` file with `DISCORD_BOT_TOKEN=`
**Created:** Via `ccs config channels --set-token discord=`
**Delete:** Disables Discord channel auto-enable
**Content:**
```
DISCORD_BOT_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4...
```
**Related:**
* [Official Channels](/reference/cli-commands#official-channels-configuration)
* `channels.selected` config key
***
## Cache Files
### `~/.ccs/cache/usage.json`
**Purpose:** Usage analytics cache (in-memory format)
**Format:** JSON
**Created:** First Claude Code session
**Delete:** Safe (analytics will reset)
**Structure:**
```json theme={null}
{
"daily": {
"2025-12-15": {
"requests": 42,
"tokens": 125000,
"models": {
"claude-sonnet-4.5": 30,
"gemini-2.5-pro": 12
}
}
}
}
```
**Use Cases:**
* Track daily/monthly usage
* Model distribution analysis
* Cost estimation
**Related:**
* Dashboard Analytics page
* `/api/usage/*` endpoints
***
### `~/.ccs/.cache/usage-cache.json`
**Purpose:** Persistent usage cache (disk format)
**Format:** JSON
**Created:** On shutdown/periodic sync
**Delete:** Safe (will rebuild from sessions)
**Difference from `cache/usage.json`:**
* `cache/usage.json` - In-memory, fast access
* `.cache/usage-cache.json` - Persistent, survives restarts
**Structure:** Same as `cache/usage.json`
**Sync Behavior:**
* Write on graceful shutdown
* Periodic sync every 5 minutes (if dirty)
* Load on startup
***
### `~/.ccs/cache/update-check.json`
**Purpose:** Update notification cache
**Format:** JSON
**Created:** First update check
**Delete:** Safe (will re-check immediately)
**Structure:**
```json theme={null}
{
"lastCheck": "2025-12-15T10:00:00Z",
"latestVersion": "7.3.0",
"currentVersion": "7.2.5",
"updateAvailable": true,
"releaseUrl": "https://github.com/kaitranntt/ccs/releases/tag/v7.3.0"
}
```
**Cache Duration:** 24 hours
**Related:**
* `ccs update` - Manual update
* Startup update notifications
***
## Logs
### `~/.ccs/logs/`
**Purpose:** CCS-owned structured runtime logs
**Format:** JSONL
**Created:** As CCS runtime events are written
**Delete:** Safe (though you lose local history)
**Primary files:**
* `current.jsonl` - active structured log stream
* `archive/` - rotated segments pruned by `logging.retain_days`
**Controlled by:**
```yaml theme={null}
logging:
enabled: true
level: info
rotate_mb: 10
retain_days: 7
redact: true
live_buffer_size: 250
```
Structured logs may still contain sensitive operational context. Keep
redaction enabled unless you are debugging locally and understand the
tradeoff.
***
### `~/.ccs/cliproxy/logs/`
**Purpose:** CLIProxy runtime log files
**Format:** Plain text
**Created:** When `cliproxy.logging.enabled: true`
**Delete:** Safe (via `ccs cleanup`)
**Configuration:**
```yaml theme={null}
cliproxy:
logging:
enabled: false # Default: false
request_log: false # Verbose request/response logging
```
CLIProxy logs can consume significant disk space. Enable only for debugging.
**Log Types:**
* `error.log` - Error messages only
* `request.log` - HTTP request/response (if `request_log: true`)
* `debug.log` - Verbose debug output
**Related:**
* [Config Schema: cliproxy.logging](/reference/config-schema#cliproxyloggingenabled)
* [Dashboard Logs](/features/dashboard/logs)
***
## Legacy Files (Pre-v8)
### `~/.ccs/config.json` (deprecated)
**Status:** Deprecated in v8
**Migration:** Automatically migrated to `config.yaml`
**Delete:** After successful migration
**Related:**
* [Migration Guide](/reference/migration-v6-v7)
* `ccs migrate` command
***
### `~/.ccs/profiles.json` (deprecated)
**Status:** Deprecated in v8
**Migration:** Merged into `config.yaml` under `accounts` section
**Delete:** After successful migration
***
## Backup Files
### `~/.ccs/backup-v1-YYYY-MM-DD/`
**Purpose:** Migration backups
**Created:** During config migration (v1 → v8)
**Delete:** Safe after verifying migration success
**Contains:**
* `config.json` - Legacy config
* `profiles.json` - Legacy profiles
* `usage-cache.json` - Pre-v8 cache
**Recovery:**
```bash theme={null}
ccs migrate --rollback ~/.ccs/backup-v1-2025-12-15/
```
**List Backups:**
```bash theme={null}
ls -la ~/.ccs/backup-*/
```
***
## Shared Data
### `~/.ccs/shared/`
Shared profiles use `~/.ccs/shared/` as the managed access layer for resources whose canonical source is under `~/.claude/`:
```
~/.ccs/shared/
├── commands/ -> ~/.claude/commands/
├── skills/ -> ~/.claude/skills/
├── agents/ -> ~/.claude/agents/
├── plugins/ # Managed shared plugin layout
├── settings.json -> ~/.claude/settings.json
└── CLAUDE.md -> ~/.claude/CLAUDE.md
```
On macOS and Linux these entries are symlinks. Windows can fall back to copies
when symlinks are unavailable. `ccs sync` repairs the shared access layer.
`CLAUDE.md` is shared by default for non-bare account profiles. CCS creates an
empty canonical file when no copy exists. If the canonical file is missing,
one unique existing variant is adopted; multiple distinct variants are kept as
`CLAUDE.md.ccs-shared-conflict[-N]` files for explicit recovery. When the
canonical file exists, it always wins and any divergent copy is also preserved
with that suffix.
```bash theme={null}
ccs sync
```
* [Shared Data](/features/config/shared-data)
* [Shared Data Architecture](/reference/architecture#shared-data)
***
## Instance Directories (Account Profiles)
### `~/.ccs/instances//`
Account profiles use independent `CLAUDE_CONFIG_DIR` roots. Credentials,
sessions, and history remain profile-specific, while non-bare profiles link
managed shared resources at the instance root:
```
~/.ccs/instances/work/
├── .credentials.json # Profile credentials
├── settings.json -> ~/.ccs/shared/settings.json
├── CLAUDE.md -> ~/.ccs/shared/CLAUDE.md
├── commands/ -> ~/.ccs/shared/commands/
├── skills/ -> ~/.ccs/shared/skills/
├── agents/ -> ~/.ccs/shared/agents/
├── session-env/ # Profile session state
├── todos/ # Profile todo state
└── logs/ # Profile logs
```
Profiles created with `--bare`, or switched to `profile-local`, do not use the
managed shared links. See [Claude Accounts](/providers/concepts/claude-accounts).
***
## Temporary Files
### `~/.ccs/tmp/`
**Purpose:** Temporary files during operations
**Format:** Various
**Created:** During migrations, updates, etc.
**Delete:** Safe (auto-cleaned)
**Auto-Cleanup:**
* On successful operation completion
* Via `ccs cleanup`
* On startup (files older than 24h)
***
## Quick Reference Table
| Path | Purpose | Format | Delete Safe? |
| -------------------------------------- | --------------------------- | -------- | ---------------------- |
| `~/.ccs/config.yaml` | Main config | YAML | No (reset CCS) |
| `~/.ccs/*.settings.json` | API profile env vars | JSON | Yes (profile breaks) |
| `~/.ccs/xai.settings.json` | xAI provider settings | JSON | Yes (provider resets) |
| `~/.ccs/cliproxy/auth/xai-*.json` | xAI OAuth credentials | JSON | No (re-auth needed) |
| `~/.ccs/cliproxy/sessions.json` | Session tracking | JSON | Yes (sessions reset) |
| `~/.ccs/cliproxy/sessions-{port}.json` | Port-specific sessions | JSON | Yes |
| `~/.ccs/cliproxy/accounts.json` | OAuth accounts | JSON | No (re-auth needed) |
| `~/.ccs/cliproxy/config-{port}.yaml` | Port configs | YAML | Yes (regenerates) |
| `~/.ccs/cliproxy/bin/original/` | CLIProxyAPI binary dir | Binary | Yes (reinstalls) |
| `~/.ccs/cliproxy/bin/plus/` | CLIProxyAPIPlus binary dir | Binary | Yes (reinstalls) |
| `~/.ccs/browser/chrome-user-data/` | Browser attach profile | Dir | Yes |
| `~/.ccs/mcp/ccs-browser-server.cjs` | Browser MCP runtime | JS | Yes (recreates) |
| `~/.ccs/cache/usage.json` | In-memory cache | JSON | Yes (rebuilds) |
| `~/.ccs/.cache/usage-cache.json` | Persistent cache | JSON | Yes (rebuilds) |
| `~/.ccs/logs/` | Debug logs | Text | Yes |
| `~/.ccs/cliproxy/logs/` | CLIProxy logs | Text | Yes |
| `~/.ccs/backup-*/` | Migration backups | Mixed | Yes (after verify) |
| `~/.claude/CLAUDE.md` | Canonical user instructions | Markdown | No |
| `~/.claude/channels/telegram/.env` | Telegram bot token | .env | Yes (disables channel) |
| `~/.claude/channels/discord/.env` | Discord bot token | .env | Yes (disables channel) |
***
## Cleanup Strategy
```bash theme={null}
ccs cleanup
```
Run monthly or when disk space is low.
```bash theme={null}
rm -rf ~/.ccs/logs/*
rm -rf ~/.ccs/cliproxy/logs/*
rm -rf ~/.ccs/tmp/*
rm -rf ~/.ccs/backup-*/
```
Run if troubleshooting or resetting environment.
```bash theme={null}
rm -rf ~/.ccs/
ccs setup
```
Only if reinstalling CCS completely.
***
## Related Resources
* [Configuration Schema](/reference/config-schema)
* [Migration Guide](/reference/migration-v6-v7)
* [Troubleshooting](/reference/troubleshooting)
* [CLI Commands](/reference/cli-commands)
# Migration Guide (v6 → v7)
Source: https://docs.ccs.kaitran.ca/reference/migration-v6-v7
Complete guide for migrating from CCS v5 to v7, including v6 features, v7.1 remote proxy support, v7.2 new providers, and breaking changes
# Migration Guide: v6 → v7
Complete migration guide covering all features introduced in v6 and v7, including customizable auth, variant-specific configuration, remote CLIProxy support, new OAuth providers, and token refresh improvements.
***
## Version Overview
| Version | Release | Key Features |
| ------- | ------- | --------------------------------------------------------------- |
| v7.2 | 2026-01 | Kiro OAuth support, GHCP Device Code flow |
| v7.1 | 2025-12 | Remote CLIProxy support, proactive token refresh |
| v6 | 2025-11 | Customizable auth tokens, variant-specific auth, port isolation |
| v5 | 2025-10 | Remote proxy configuration (deprecated in v7.1) |
***
## Breaking Changes Summary
Review all breaking changes before upgrading to v7.
### v7.2 Breaking Changes
**None** - Fully backward compatible with v7.1
### v7.1 Breaking Changes
**None** - Fully backward compatible with v6
### v6 Breaking Changes
**Config Schema:**
* `config.json` → `config.yaml` (automatic migration)
* New required field: `version: 6`
* `cliproxy.auth` structure changed (automatic migration)
**CLI Flags:**
* `--proxy-server` deprecated → use `--proxy-host`
* `--proxy-auth` deprecated → use `--proxy-auth-token`
***
## Migration Checklist
```bash theme={null}
cp ~/.ccs/config.yaml ~/.ccs/config.yaml.backup
cp ~/.ccs/cliproxy/accounts.json ~/.ccs/cliproxy/accounts.json.backup
```
CCS creates automatic backups, but a manual backup is recommended.
```bash theme={null}
npm update -g @kaitranntt/ccs
# Or force reinstall
npm install -g @kaitranntt/ccs@latest
```
```bash theme={null}
ccs --version
ccs doctor
ccs doctor --fix
```
```bash theme={null}
ccs
ccs codex --auth
ccs codex
```
***
## New Features in v7.2
### 1. Kiro OAuth Support (HIGH PRIORITY)
**What's New:**
* Full OAuth support for Kiro provider (AWS Bedrock Claude)
* Browser-based authentication flow
* Token import from Kiro IDE
**Migration Steps:**
```bash theme={null}
# First-time Kiro setup
ccs kiro --auth
```
Browser opens for AWS SSO login. Authenticate and grant access.
```bash theme={null}
# Import token from Kiro IDE
ccs kiro --import
```
Automatically imports credentials from `~/.kiro/` directory.
```yaml theme={null}
# config.yaml - Disable incognito for persistent AWS session
cliproxy:
kiro_no_incognito: true
```
Or use the CLI flag:
```bash theme={null}
ccs kiro --no-incognito
```
**Configuration:**
```yaml theme={null}
cliproxy:
oauth_accounts:
kai-work: "kai@work.com" # Kiro account
variants:
kiro-dev:
provider: kiro
account: kai-work
settings: "~/.ccs/kiro-dev.settings.json"
kiro_no_incognito: false # Default: false (use incognito)
```
**CLI Flags:**
| Flag | Purpose |
| ----------------- | --------------------------------------- |
| `--auth` | Authenticate via browser OAuth |
| `--import` | Import token from Kiro IDE |
| `--no-incognito` | Use normal browser mode (saves session) |
| `--use ` | Switch Kiro account |
| `--accounts` | List all Kiro accounts |
**Use Cases:**
* Access AWS Bedrock Claude via Kiro
* Use Claude via AWS SSO with MFA
* Persistent AWS session (no re-auth)
***
### 2. GHCP Device Code Flow (HIGH PRIORITY)
**What's New:**
* GitHub Copilot (GHCP) provider now uses Device Code flow
* No headless browser required
* Better support for SSH/remote environments
**Migration Steps:**
```bash Old Flow (v7.1 and earlier) theme={null}
# Headless browser flow (deprecated)
ccs ghcp --headless
# Copy URL, open in local browser
```
```bash New Flow (v7.2+) theme={null}
# Device Code flow (automatic)
ccs ghcp --auth
# Output:
# Visit: https://github.com/login/device
# Enter code: ABCD-1234
# Waiting for authentication...
```
**Configuration:**
```yaml theme={null}
cliproxy:
oauth_accounts:
kai-personal: "kai@github.com"
variants:
ghcp-work:
provider: ghcp
account: kai-personal
```
**CLI Usage:**
```bash theme={null}
# First-time setup
ccs ghcp --auth
# Add another GitHub account
ccs ghcp --auth --add
# Switch accounts
ccs ghcp --use work-account
# List accounts
ccs ghcp --accounts
```
**Benefits:**
* Works in SSH sessions
* No browser automation
* More reliable auth flow
* Better UX for remote development
***
## New Features in v7.1
### 3. Remote CLIProxy Support (HIGH PRIORITY)
**What's New:**
* Connect to remote CLIProxyAPI server
* Share proxy across multiple machines
* Fallback to local proxy if remote unreachable
**Migration Steps:**
```yaml theme={null}
cliproxy_server:
remote:
enabled: true
host: "proxy.example.com"
port: 8443 # Optional (default: 443 for HTTPS, 80 for HTTP)
protocol: "https" # http or https
auth_token: "your-token-123"
management_key: "mgmt-key-456" # Optional (falls back to auth_token)
timeout: 5000 # Optional (default: 2000ms)
fallback:
enabled: true # Graceful degradation
local:
port: 8317
auto_start: true # Auto-start local if remote fails
```
```bash theme={null}
ccs glm
```
This will try the remote proxy first. Check logs for connection status:
```text theme={null}
[i] Connecting to remote proxy at https://proxy.example.com:8443
[OK] Remote proxy connected
```
```bash theme={null}
ccs codex --remote-only
```
Fails with `PROXY_ERROR` if the remote proxy is unreachable.
**CLI Flags:**
| Flag | Purpose | Priority |
| -------------------------------- | -------------------------- | -------- |
| `--proxy-host ` | Remote proxy hostname | HIGH |
| `--proxy-port ` | Remote proxy port | HIGH |
| `--proxy-auth-token ` | Remote auth token | HIGH |
| `--proxy-protocol ` | Protocol (default: http) | MEDIUM |
| `--local-proxy` | Force local mode | MEDIUM |
| `--remote-only` | Fail if remote unreachable | MEDIUM |
| `--proxy-timeout ` | Health check timeout | LOW |
| `--allow-self-signed` | Accept self-signed certs | LOW |
**Environment Variables:**
```bash theme={null}
export CCS_PROXY_HOST="proxy.example.com"
export CCS_PROXY_PORT="8443"
export CCS_PROXY_AUTH_TOKEN="your-token-123"
export CCS_PROXY_PROTOCOL="https"
export CCS_PROXY_FALLBACK_ENABLED="true"
export CCS_PROXY_TIMEOUT="5000"
export CCS_ALLOW_SELF_SIGNED="false"
```
**Use Cases:**
* Centralized proxy for teams
* Share OAuth credentials across machines
* Reduce per-machine setup
* Better security (credentials on server only)
**Architecture:**
```
┌─────────────┐ ┌──────────────────┐
│ Machine A │ │ │
│ ccs codex │─────────▶│ Remote Proxy │
└─────────────┘ │ (8443/HTTPS) │
│ │
┌─────────────┐ │ - OAuth tokens │
│ Machine B │─────────▶│ - Shared cache │
│ ccs codex │ │ - Session mgmt │
└─────────────┘ └──────────────────┘
│
▼
┌──────────────────┐
│ Gemini API │
│ Codex API │
│ Antigravity API │
└──────────────────┘
```
**Security:**
* Use HTTPS for production
* Separate `management_key` for admin endpoints
* Rotate tokens regularly
* Use firewall rules for access control
***
### 4. Proactive Token Refresh (HIGH PRIORITY)
**What's New:**
* Automatic token refresh 5 minutes before expiration
* Prevents mid-session auth failures
* Supports Gemini, Codex, Antigravity, Qwen, iFlow
**Migration Steps:**
**No action required** - Automatic for all OAuth providers
**How It Works:**
Before each API request, CCS checks token expiration.
If token expires in \<5 minutes, refresh automatically.
User experiences no interruption.
**Configuration:**
```yaml theme={null}
# No configuration needed - enabled by default
cliproxy:
providers:
- gemini # Auto-refresh enabled
- codex # Auto-refresh enabled
- agy # Auto-refresh enabled
```
**Logging:**
Enable debug logs to see refresh activity:
```bash theme={null}
CCS_DEBUG=1 ccs codex
# Output:
# [i] Token expires in 4m 32s, refreshing...
# [OK] Token refreshed, new expiry: 2025-12-16T15:30:00Z
```
**Benefits:**
* No mid-session auth failures
* Better user experience
* Reduced support tickets
***
## New Features in v6
### 5. Customizable Management Key (HIGH PRIORITY)
**What's New:**
* Separate `management_key` from `api_key`
* Enhanced security for admin endpoints
* Per-variant auth override
**Migration from v5:**
```yaml v5 Config (Automatic Migration) theme={null}
cliproxy:
auth: "single-key-for-all"
```
```yaml v6 Config (After Migration) theme={null}
cliproxy:
auth:
api_key: "ccs-internal-managed" # For API requests
management_secret: "ccs" # For management endpoints
```
**Configuration:**
```yaml theme={null}
cliproxy:
auth:
api_key: "custom-api-key-123"
management_secret: "custom-mgmt-secret-456"
variants:
my-gemini:
provider: gemini
auth:
api_key: "variant-api-key"
management_secret: "variant-mgmt-secret"
```
**Use Cases:**
* Separate API vs admin credentials
* Different auth per environment (dev/prod)
* Enhanced security for production
***
### 6. Variant-Specific Auth (HIGH PRIORITY)
**What's New:**
* Per-variant auth override
* Different credentials per variant
* Isolate dev/prod environments
**Migration Steps:**
````yaml # Before v6 - Single auth for all variants cliproxy: auth: theme={null}
"global-key" variants: codex-dev: provider: codex codex-prod: provider:
codex ```
```yaml # v6+ - Per-variant auth cliproxy: auth: api_key: "global-default"
management_secret: "global-secret" variants: codex-dev: provider: codex
auth: api_key: "dev-key" management_secret: "dev-secret" codex-prod:
provider: codex auth: api_key: "prod-key" management_secret: "prod-secret"
````
**Use Cases:**
* Separate dev/prod credentials
* Per-team auth keys
* Testing with different API keys
* Security isolation
***
### 7. Port Isolation for Variants (MEDIUM PRIORITY)
**What's New:**
* Assign unique ports to variants (8318-8417)
* Run multiple variants concurrently
* Avoid port conflicts
**Migration Steps:**
```yaml theme={null}
cliproxy:
variants:
codex-dev:
provider: codex
port: 8318 # NEW: Explicit port assignment
codex-prod:
provider: codex
port: 8319 # Different port = concurrent execution
custom-qwen:
provider: qwen
port: 8320
```
**Port Range:**
* **8317:** Default local proxy (reserved)
* **8318-8417:** Available for variants (100 ports)
**Use Cases:**
* Run dev and prod simultaneously
* Multi-user environments
* Isolated testing
**CLI Usage:**
```bash theme={null}
# Terminal 1
ccs codex-dev # Port 8318
# Terminal 2 (concurrently)
ccs codex-prod # Port 8319
```
***
## Configuration Priority Resolution
CCS resolves configuration values in this priority order:
```
1. CLI Flags (highest)
↓
2. Environment Variables
↓
3. config.yaml
↓
4. Defaults (lowest)
```
**Example:**
```bash CLI Flag (Wins) theme={null}
ccs codex --proxy-host proxy.example.com
```
```bash Environment Variable theme={null}
CCS_PROXY_HOST=proxy.example.com ccs codex
```
```yaml Config File theme={null}
cliproxy_server:
remote:
host: "proxy.example.com"
```
**Result:** CLI flag overrides env var, env var overrides config file.
***
## Multi-Account OAuth Workflow
**New in v6+**: Multi-account support for all OAuth providers
```bash theme={null}
ccs codex --auth
```
Browser opens for authentication. The account is saved with the email as the
default nickname.
```bash theme={null}
ccs codex --auth --add
```
Authenticate with a different account.
```bash theme={null}
ccs codex --accounts
```
Example output:
```text theme={null}
kai@personal.com (default)
kai@work.com
```
```bash theme={null}
ccs codex --use kai@work.com
```
```bash theme={null}
ccs codex --nickname work-account
```
After renaming, switch with:
```bash theme={null}
ccs codex --use work-account
```
**Configuration:**
```yaml theme={null}
cliproxy:
oauth_accounts:
personal: "kai@personal.com"
work: "kai@work.com"
variants:
gemini-personal:
provider: gemini
account: personal # Use specific account
gemini-work:
provider: gemini
account: work
```
**CLI Flags:**
| Flag | Purpose |
| ------------------- | -------------------------------- |
| `--accounts` | List all accounts |
| `--use ` | Switch default account |
| `--auth` | Authenticate (current account) |
| `--auth --add` | Add new account |
| `--nickname ` | Rename current account |
| `--logout` | Clear tokens for current account |
***
## Troubleshooting Migration Issues
### Issue: Migration Failed
```
[X] CONFIG_ERROR: Failed to migrate config
```
```bash theme={null}
# Check migration status
ccs doctor
# Manual migration
ccs migrate
# Rollback if needed
ls ~/.ccs/backup-*/
ccs migrate --rollback ~/.ccs/backup-v1-2025-12-15/
```
***
### Issue: Remote Proxy Connection Failed
```
[X] PROXY_ERROR: Failed to connect to remote proxy
```
```bash theme={null}
# Test connection
curl -H "x-api-key: your-token" https://proxy.example.com:8443/health
# Check firewall/network
telnet proxy.example.com 8443
# Force local fallback
ccs codex --local-proxy
# Debug mode
CCS_DEBUG=1 ccs codex
```
***
### Issue: Token Refresh Failed
```
[X] AUTH_ERROR: Token refresh failed
```
```bash theme={null}
# Re-authenticate
ccs codex --logout
ccs codex --auth
# Check token expiration
cat ~/.ccs/cliproxy/accounts.json | jq
# Enable debug logs
CCS_DEBUG=1 ccs codex
```
***
### Issue: Port Conflict
```
[X] PROXY_ERROR: Port 8318 already in use
```
```bash theme={null}
# Find process using port
lsof -i :8318 # macOS/Linux
netstat -ano | findstr :8318 # Windows
# Kill process
kill
# Or assign different port
# config.yaml:
# cliproxy.variants.my-gemini.port: 8319
```
***
## Rollback Guide
If migration fails, rollback to previous version:
```bash theme={null}
killall ccs
killall cli-proxy-api
```
```bash theme={null}
# List backups
ls ~/.ccs/backup-*/
# Restore
ccs migrate --rollback ~/.ccs/backup-v1-2025-12-15/
```
```bash theme={null}
npm install -g @kaitranntt/ccs@6.5.0
```
```bash theme={null}
ccs --version
ccs doctor
```
***
## Feature Adoption Roadmap
Recommended adoption order for v6/v7 features:
* Update to v7.2 - Verify automatic migration - Test existing profiles - Run
`ccs doctor --fix`
* Set up Kiro OAuth - Migrate GHCP to Device Code flow - Test multi-account
workflows
* Deploy remote CLIProxy (if team) - Configure fallback - Test connection
stability
* Implement port isolation - Configure variant-specific auth - Set up
monitoring/analytics
***
## Environment Variables Reference
New environment variables in v6/v7:
| Variable | Version | Purpose | Priority |
| ---------------------------- | ------- | ---------------------------------- | -------- |
| `CCS_PROXY_HOST` | v7.1 | Remote proxy hostname | HIGH |
| `CCS_PROXY_PORT` | v7.1 | Remote proxy port | HIGH |
| `CCS_PROXY_AUTH_TOKEN` | v7.1 | Remote proxy auth token | HIGH |
| `CCS_PROXY_PROTOCOL` | v7.1 | Remote proxy protocol (http/https) | MEDIUM |
| `CCS_PROXY_FALLBACK_ENABLED` | v7.1 | Fallback to local proxy | MEDIUM |
| `CCS_PROXY_TIMEOUT` | v7.1 | Remote health check timeout | LOW |
| `CCS_ALLOW_SELF_SIGNED` | v7.1 | Accept self-signed certs | LOW |
| `CCS_UNIFIED_CONFIG` | v6 | Enable unified config mode | MEDIUM |
| `CCS_MIGRATE` | v6 | Trigger auto-migration | MEDIUM |
| `CCS_DEBUG` | All | Verbose logging | HIGH |
***
## API Endpoints (New in v7)
Dashboard API endpoints for remote proxy management:
### CLIProxy Control
| Endpoint | Method | Purpose |
| ---------------------------- | ------ | --------------------- |
| `/api/cliproxy/proxy-status` | GET | Get proxy status |
| `/api/cliproxy/proxy-start` | POST | Start proxy |
| `/api/cliproxy/proxy-stop` | POST | Stop proxy |
| `/api/cliproxy/update-check` | GET | Check for updates |
| `/api/cliproxy/models` | GET | List available models |
| `/api/cliproxy/error-logs` | GET | Get error logs |
### Usage Analytics
| Endpoint | Method | Purpose |
| --------------------- | ------ | ------------------ |
| `/api/usage/summary` | GET | Usage summary |
| `/api/usage/daily` | GET | Daily breakdown |
| `/api/usage/hourly` | GET | Hourly breakdown |
| `/api/usage/models` | GET | Model distribution |
| `/api/usage/insights` | GET | AI insights |
**Related:**
* [API Reference](/reference/api-cliproxy)
* [API Reference](/reference/api-usage)
***
## Next Steps
Complete config.yaml v6 reference
Where CCS stores data
All CLI flags and options
Common issues and solutions
***
## Related Resources
* [Configuration Schema Reference](/reference/config-schema)
* [CLI Commands Reference](/reference/cli-commands)
* [CLI Flags Reference](/reference/cli-flags)
* [File Locations Reference](/reference/file-locations)
* [Error Codes Reference](/reference/error-codes)
* [Troubleshooting Guide](/reference/troubleshooting)
# Troubleshooting
Source: https://docs.ccs.kaitran.ca/reference/troubleshooting
Common issues and solutions
# Troubleshooting
Common issues and their solutions.
For detailed error code reference and recovery strategies, see [Error Codes](/reference/error-codes).
## Installation Issues
### Config File Not Found After npm Install
**Symptom**:
```
Config file not found: /home/user/.ccs/config.yaml
```
**Cause**: Installed with `--ignore-scripts` flag.
**Solution**:
```bash theme={null}
npm install -g @kaitranntt/ccs --force
```
### PATH Not Updated
**Symptom**: `ccs` command not found after install.
**Solution**:
1. Restart your terminal
2. Or manually add to PATH:
* macOS/Linux: Add `~/.local/bin` to PATH
* Windows: Add `%USERPROFILE%\.ccs` to PATH
## Windows-Specific
### PowerShell Execution Policy
**Error**: "cannot be loaded because running scripts is disabled"
**Solution**:
```powershell theme={null}
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
### Claude CLI Not Found
```powershell theme={null}
where.exe claude
```
If missing, install from [Claude docs](https://docs.claude.com/en/docs/claude-code/installation).
## Claude CLI in Non-Standard Location
### Set CCS\_CLAUDE\_PATH
```powershell theme={null}
$env:CCS_CLAUDE_PATH = "D:\Program Files\Claude\claude.exe"
[Environment]::SetEnvironmentVariable("CCS_CLAUDE_PATH", $env:CCS_CLAUDE_PATH, "User")
```
```bash theme={null}
echo 'export CCS_CLAUDE_PATH="/opt/custom/claude"' >> ~/.bashrc
source ~/.bashrc
```
## Configuration Issues
### Profile Not Found
**Error**: `Profile 'foo' not found in ~/.ccs/config.yaml`
**Solution**: Add profile to config:
```yaml theme={null}
profiles:
foo: ~/.ccs/foo.settings.json
```
### Settings File Missing
**Error**: `Settings file not found: ~/.ccs/foo.settings.json`
**Solution**: Create the settings file or fix path in config.
### Default Profile Missing
**Error**: `Profile 'default' not found`
**Solution**: Add default profile:
```yaml theme={null}
default: default
profiles:
default: ~/.claude/settings.json
```
### Codex config.toml Cannot Be Parsed
If Codex writes a model migration and joins it to the next TOML table header, the Control Center disables structured controls to avoid overwriting the invalid file.
**Solution:** Open `ccs config`, select **Codex config.toml**, then choose **Preview one-newline repair**. CCS creates an unsaved editor draft that inserts only the missing newline. Review the diff and select **Save** to write it. The save uses the file version observed when the draft was created, so it refuses a concurrent change instead of overwriting it.
The preview appears only for this exact migration-table boundary. For any other TOML error, correct the raw TOML manually and save it after the validation message clears.
## Quota Issues
### Quota Shows "N/A (fetch unavailable)"
When quota cannot be fetched, CCS displays "N/A" instead of a percentage.
**Causes:**
* Network connectivity issues
* API rate limiting (5-second timeout)
* Account tier lacks quota API access (403 Forbidden)
* Token expired (401 Unauthorized)
**Solutions:**
1. **Check connectivity:**
```bash theme={null}
curl https://cloudcode-pa.googleapis.com
```
2. **Run diagnostics with verbose mode:**
```bash theme={null}
ccs cliproxy status --verbose
ccs codex --verbose
```
3. **Verify account tier:**
Some free-tier accounts don't have quota API access. Upgrade to paid tier if needed.
4. **Refresh authentication:**
```bash theme={null}
ccs codex --auth
```
***
### Quota Fetch Error Codes
| Error | HTTP Status | Cause | Solution |
| ------------- | ----------- | ---------------------------- | ----------------------------------------- |
| Forbidden | 403 | Account tier lacks quota API | Upgrade account tier |
| Unauthorized | 401 | Token expired/invalid | Run `--auth` to refresh |
| Timeout | - | Network issues | Check connectivity, increase timeout |
| Unprovisioned | - | Account not activated | Sign into Gemini Code Assist in IDE first |
***
### Quota Shows 0 But Account Not Exhausted
**Possible causes:**
* Quota not yet refreshed (30-second cache TTL)
* All models at 0% (account exhausted)
* Fetch returned null (treated as unknown)
**Distinguish null vs 0:**
* `null` = fetch failed → shows "N/A"
* `0` = quota exhausted → shows "0%"
**Solution:**
```bash theme={null}
# Force quota refresh with verbose
ccs cliproxy status --verbose
# Wait 30 seconds for cache to expire
```
***
### Account Skipped in Rotation
Accounts are skipped when:
1. Quota below threshold (default: 5%)
2. Account is paused manually
3. Account in cooldown (5 minutes after exhaustion)
4. Quota fetch returned null
**Check account status:**
```bash theme={null}
ccs cliproxy status agy
```
**Resume paused account:**
```bash theme={null}
ccs cliproxy resume agy user@gmail.com
```
## Common Problems
### Claude CLI Not Found
**Solution**: Install from [official documentation](https://docs.claude.com/en/docs/claude-code/installation).
### Permission Denied
```bash theme={null}
chmod +x ~/.local/bin/ccs
```
## Debug Mode
Enable verbose output:
```bash theme={null}
ccs --verbose glm
```
Shows:
* Config file being read
* Profile being selected
* Settings file being used
* Command being executed
## Disable Colors
```bash theme={null}
export NO_COLOR=1
ccs glm
```
## Getting Help
1. Check [GitHub Issues](https://github.com/kaitranntt/ccs/issues)
2. Create new issue with:
* Operating system
* CCS version (`ccs --version`)
* Exact error message
* Steps to reproduce
## Network Proxy Support
Available since v7.37.0 - CLIProxy respects standard proxy environment variables for network requests.
CCS and CLIProxy honor standard HTTP proxy environment variables for:
* Binary downloads (CLIProxyAPI installation)
* API requests to OAuth providers
* Model catalog sync
### Configuration
Set standard proxy environment variables:
```bash theme={null}
# HTTP proxy
export http_proxy="http://proxy.example.com:8080"
# HTTPS proxy
export https_proxy="http://proxy.example.com:8080"
# No proxy for specific hosts
export NO_PROXY="localhost,127.0.0.1,.internal"
```
### Troubleshooting Proxy Issues
**Connection failures behind proxy:**
```bash theme={null}
# Verify proxy settings
echo $http_proxy
echo $https_proxy
# Test connectivity
curl -I https://api.gemini.google.com
# Enable debug mode
export CCS_DEBUG=1
ccs codex "test prompt"
```
**Proxy authentication:**
Most proxies accept credentials in URL format:
```bash theme={null}
export http_proxy="http://username:password@proxy.example.com:8080"
```
**SSL inspection/MITM proxies:**
If corporate proxy inspects SSL traffic, you may need to trust the proxy's CA certificate:
```bash theme={null}
# Add CA certificate to system trust store
# Linux
sudo cp proxy-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
# macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain proxy-ca.crt
```
## OAuth Callback Tracing
When an OAuth login fails (URL not displayed, callback never observed, token
exchange error, etc.), CCS now emits branch-specific diagnostics instead of a
generic "token not found" message.
For deep debugging, enable the opt-in JSONL file sink:
```bash theme={null}
export CCS_OAUTH_LOG_FILE=1
ccs auth create work # or any OAuth-triggering command
```
* Log path: `~/.ccs/logs/oauth-YYYYMMDD.log` (mode `0o600`, rotated per day)
* Format: JSONL, one event per line
* Redaction: tokens, codes, and PKCE verifiers are stripped before write
* Sinks: in-memory ring buffer (always on), verbose stdout (with `CCS_DEBUG=1`),
file sink (opt-in via `CCS_OAUTH_LOG_FILE=1`)
Attach the log file when reporting OAuth issues — it contains per-phase timing
(URL display, callback wait, token exchange, persistence) with secrets removed.
# Docker Deployment
Source: https://docs.ccs.kaitran.ca/tutorials/docker-deployment
Run the CCS Dashboard in Docker with persistent configuration and automatic restarts
## Overview
Docker deployment allows you to:
* **Isolated environment** - Run CCS Dashboard in a container with all dependencies
* **Persistent configuration** - Keep your config, credentials, and CLI tools across restarts
* **Resource limits** - Control memory and CPU usage for production deployments
* **Easy deployment** - Deploy to any system with Docker installed
* **Pre-installed CLIs** - claude, gemini, grok, opencode, and ccs ready to use
## Architecture
```
┌─────────────────────────────────────────────────────┐
│ Docker Container (ccs-dashboard) │
│ │
│ Port 3000 ──▶ CCS Dashboard Web UI │
│ Port 8317 ──▶ CLIProxy API (OAuth providers) │
│ │
│ Volumes: │
│ • /home/node/.ccs (CCS config, credentials) │
│ • /home/node/.claude (Claude sessions, logs) │
│ • /home/node/.opencode (OpenCode config) │
│ • /home/node/.grok-cli (Grok CLI config) │
└─────────────────────────────────────────────────────┘
```
## Prerequisites
* Docker 20.10+ or Docker Desktop
* Docker Compose 2.0+ (optional, for compose setup)
* 1GB free disk space
* Ports 3000 and 8317 available
## Quick Start (Docker Run)
Clone the CCS repository and build the Docker image:
```bash theme={null}
git clone https://github.com/kaitranntt/ccs.git
cd ccs
docker build -f docker/Dockerfile -t ccs-dashboard:latest .
```
Build time: \~5-10 minutes (one-time operation).
Start the CCS Dashboard container:
```bash theme={null}
docker run -d \
--name ccs-dashboard \
--restart unless-stopped \
-p 3000:3000 \
-p 8317:8317 \
-e CCS_PORT=3000 \
-v ccs_home:/home/node/.ccs \
ccs-dashboard:latest
```
**Note:** `--restart unless-stopped` ensures the container restarts on system reboot.
Open your browser and navigate to:
```
http://localhost:3000
```
The CLIProxy API is available at `http://localhost:8317` (used by OAuth providers and Dashboard features).
## Docker Compose Setup
For production deployments, use Docker Compose for easier management.
Create a `.env` file in the `docker/` directory to customize ports and configuration:
```bash theme={null}
# Ports
CCS_DASHBOARD_PORT=3000
CCS_CLIPROXY_PORT=8317
# CCS Configuration
CCS_DEBUG=0
NO_COLOR=0
# Remote Proxy (optional)
CCS_PROXY_HOST=
CCS_PROXY_PORT=
CCS_PROXY_PROTOCOL=https
CCS_PROXY_AUTH_TOKEN=
# Skip Options
CCS_SKIP_PREFLIGHT=0
CCS_WEBSEARCH_SKIP=0
# Optional: legacy API key grace days after upgrades
CCS_DOCKER_LEGACY_KEY_GRACE_DAYS=14
# Optional: explicit one-time recovery for already-broken old-key clients
CCS_DOCKER_RESTORE_LEGACY_API_KEY=0
```
From the repository root:
```bash theme={null}
docker-compose -f docker/docker-compose.yml up -d
```
View logs:
```bash theme={null}
docker-compose -f docker/docker-compose.yml logs -f
```
```bash theme={null}
docker-compose -f docker/docker-compose.yml down
```
To remove volumes (delete all config):
```bash theme={null}
docker-compose -f docker/docker-compose.yml down -v
```
## CLIProxy API Key Rotation
New integrated Docker deployments generate per-install CLIProxy API and
management secrets when custom values are missing. Upgrades from older
deployments that used the historical `ccs-internal-managed` API key keep that
legacy key valid beside the new key for 14 days by default.
The `ccs docker up` banner shows only a masked key; use `show-key --full` when
you need to copy the complete value into downstream clients.
```bash theme={null}
# Show a masked key
ccs docker show-key
# Reveal the full key for updating clients
ccs docker show-key --full
# Remove the legacy key before the grace window expires
ccs docker finalize-key-rotation
```
Set `CCS_DOCKER_LEGACY_KEY_GRACE_DAYS=0` to disable the grace window, or use a
larger value when clients need more time to update.
If a previous upgrade already replaced the old key before the grace window was
available, run once with `CCS_DOCKER_RESTORE_LEGACY_API_KEY=1` to explicitly
restore temporary compatibility. CCS will not infer this from random-looking
custom keys.
## Environment Variables
Common CCS environment variables supported in Docker:
| Variable | Purpose | Default |
| ---------------------------- | -------------------------- | ------- |
| `CCS_PORT` | Dashboard HTTP port | `3000` |
| `CCS_DEBUG` | Enable verbose logging | `0` |
| `NO_COLOR` | Disable ANSI colors | `0` |
| `CCS_SKIP_PREFLIGHT` | Skip API key validation | `0` |
| `CCS_WEBSEARCH_SKIP` | Skip WebSearch integration | `0` |
| `CCS_PROXY_HOST` | Remote proxy hostname | - |
| `CCS_PROXY_PORT` | Remote proxy port | - |
| `CCS_PROXY_PROTOCOL` | `http` or `https` | `https` |
| `CCS_PROXY_AUTH_TOKEN` | Remote proxy auth token | - |
| `CCS_PROXY_TIMEOUT` | Health check timeout (ms) | `2000` |
| `CCS_PROXY_FALLBACK_ENABLED` | Enable local fallback | `true` |
| `CCS_ALLOW_SELF_SIGNED` | Accept self-signed certs | `false` |
Example with environment variables:
```bash theme={null}
docker run -d \
--name ccs-dashboard \
--restart unless-stopped \
-p 3000:3000 \
-p 8317:8317 \
-e CCS_PORT=3000 \
-e CCS_DEBUG=1 \
-e NO_COLOR=1 \
-e CCS_PROXY_HOST="proxy.example.com" \
-e CCS_PROXY_PORT=443 \
-e CCS_PROXY_PROTOCOL="https" \
-v ccs_home:/home/node/.ccs \
ccs-dashboard:latest
```
## Persistent Storage
The container uses named volumes for persistent data:
| Volume | Container Path | Purpose |
| --------------- | ---------------------- | --------------------------------- |
| `ccs_home` | `/home/node/.ccs` | CCS config, credentials, profiles |
| `claude_home` | `/home/node/.claude` | Claude sessions, logs, todolists |
| `opencode_home` | `/home/node/.opencode` | OpenCode configuration |
| `grok_home` | `/home/node/.grok-cli` | Grok CLI configuration |
**Note:** Only `ccs_home` is required. Other volumes are optional (used if you run respective CLIs inside the container).
### Backup Configuration
```bash theme={null}
# Backup CCS config
docker run --rm -v ccs_home:/data -v $(pwd):/backup \
ubuntu tar czf /backup/ccs-backup.tar.gz /data
# Restore CCS config
docker run --rm -v ccs_home:/data -v $(pwd):/backup \
ubuntu tar xzf /backup/ccs-backup.tar.gz -C /
```
## Resource Limits
For production deployments, limit container resources to prevent overconsumption.
### Docker Run
```bash theme={null}
docker run -d \
--name ccs-dashboard \
--restart unless-stopped \
--memory=1g \
--cpus=2 \
-p 3000:3000 \
-p 8317:8317 \
-v ccs_home:/home/node/.ccs \
ccs-dashboard:latest
```
### Docker Compose
Default limits are set in `docker-compose.yml`:
```yaml theme={null}
deploy:
resources:
limits:
memory: 1G
cpus: '2'
reservations:
memory: 256M
cpus: '0.5'
```
Adjust based on workload. Monitor usage with:
```bash theme={null}
docker stats ccs-dashboard
```
## Healthcheck
The container includes a healthcheck that verifies:
1. Dashboard HTTP server (port 3000)
2. CLIProxy API (port 8317)
```yaml theme={null}
healthcheck:
test: ["CMD-SHELL", "curl -fsS --max-time 2 http://localhost:3000/ >/dev/null && curl -sS --max-time 2 http://127.0.0.1:8317/ >/dev/null"]
interval: 10s
timeout: 3s
retries: 12
start_period: 30s
```
Check health status:
```bash theme={null}
docker inspect ccs-dashboard --format='{{.State.Health.Status}}'
```
## Graceful Shutdown
CCS handles `SIGTERM` gracefully. When stopping the container:
```bash theme={null}
docker stop ccs-dashboard # Sends SIGTERM, waits 10s, then SIGKILL
docker stop -t 30 ccs-dashboard # Wait 30s for graceful shutdown
```
The `init: true` in `docker-compose.yml` ensures proper signal forwarding to the Node.js process.
## Using Pre-installed CLIs
The container includes pre-installed CLI tools for convenience.
### Execute Commands Inside Container
```bash theme={null}
# Open shell
docker exec -it ccs-dashboard bash
# Claude (non-interactive mode)
docker exec -it ccs-dashboard claude -p "Hello from Docker"
# Gemini
docker exec -it ccs-dashboard gemini "Hello from Docker"
# Grok
docker exec -it ccs-dashboard grok "Hello from Docker"
# OpenCode
docker exec -it ccs-dashboard opencode --help
# CCS
docker exec -it ccs-dashboard ccs --help
```
### Configure Credentials
Each CLI has its own authentication method. Refer to their respective documentation:
```bash theme={null}
docker exec -it ccs-dashboard claude --help
docker exec -it ccs-dashboard gemini --help
```
## Troubleshooting
### Permission Errors (EACCES)
If you see permission errors on startup:
```bash theme={null}
# Check volume permissions
docker exec ccs-dashboard ls -la /home/node/.ccs
# Fix by recreating volumes
docker-compose down -v
docker-compose up -d
```
### Port Already in Use
```bash theme={null}
# Check what's using the port
lsof -i :3000
lsof -i :8317
# Use different ports
docker run -p 4000:3000 -p 9317:8317 ...
# Or with compose
CCS_DASHBOARD_PORT=4000 CCS_CLIPROXY_PORT=9317 docker-compose up -d
```
### Container Keeps Restarting
```bash theme={null}
# Check logs for errors
docker logs ccs-dashboard --tail 50
# Check container health
docker inspect ccs-dashboard --format='{{.State.Health.Status}}'
# Check resource usage
docker stats ccs-dashboard
```
### Debug Mode
Enable verbose logging:
```bash theme={null}
docker run -e CCS_DEBUG=1 ...
```
Or update `docker-compose.yml`:
```yaml theme={null}
environment:
CCS_DEBUG: "1"
```
### Image Build Fails
Common issues:
**Network timeout during build:**
```bash theme={null}
docker build --network=host -f docker/Dockerfile -t ccs-dashboard:latest .
```
**Out of disk space:**
```bash theme={null}
docker system prune -a
```
**Cache issues:**
```bash theme={null}
docker build --no-cache -f docker/Dockerfile -t ccs-dashboard:latest .
```
## Security Best Practices
### Secrets Management
For sensitive values like `CCS_PROXY_AUTH_TOKEN`:
**Option 1: .env file (not committed to git)**
```bash theme={null}
echo "CCS_PROXY_AUTH_TOKEN=your-secret-token" >> .env
docker-compose up -d
```
**Option 2: Docker secrets (Swarm mode)**
```bash theme={null}
echo "your-secret-token" | docker secret create ccs_proxy_token -
```
### Network Security
* **Bind to localhost only** - For development:
```bash theme={null}
docker run -p 127.0.0.1:3000:3000 -p 127.0.0.1:8317:8317 ...
```
* **Use reverse proxy** - For production (nginx, traefik):
```nginx theme={null}
server {
listen 443 ssl http2;
server_name ccs.example.com;
location / {
proxy_pass http://localhost:3000;
}
}
```
### Updates
Regularly rebuild the image to get security patches:
```bash theme={null}
docker-compose build --pull
docker-compose up -d
```
## Production Deployment
For production deployments, consider:
1. **Use Docker Compose** - Easier management and configuration
2. **Set resource limits** - Prevent resource exhaustion
3. **Enable healthcheck** - Auto-restart on failures
4. **Use .env file** - Separate config from code
5. **Backup volumes** - Regular backups of `ccs_home`
6. **Monitor logs** - Centralized logging (ELK, Loki)
7. **Reverse proxy** - nginx/traefik with TLS
8. **Secret management** - Docker secrets or vault
## Next Steps
Deploy CLIProxyAPI on a remote server for centralized access
Manage multiple OAuth accounts in Docker
# Headless CI/CD
Source: https://docs.ccs.kaitran.ca/tutorials/headless-ci-cd
Use CCS in GitHub Actions and CI/CD pipelines without browser access
## Overview
Headless mode enables CCS to run in non-interactive environments:
* **CI/CD Pipelines** - GitHub Actions, GitLab CI, Jenkins
* **Automated Scripts** - Cron jobs, batch processing
* **Server-Side Tasks** - Background workers, scheduled analysis
* **No Browser Required** - 7-day session tokens eliminate OAuth flow
## How It Works
### Session Persistence
When you authenticate via browser, CCS:
1. Obtains OAuth token (expires in \~1 hour)
2. Stores refresh token (expires in 7 days)
3. Creates session file (`~/.ccs/cliproxy/sessions.json`)
4. Automatically refreshes tokens 5min before expiry
**Result:** Once authenticated locally, CI/CD can run for 7 days without re-auth.
### Headless Delegation Mode
```bash theme={null}
ccs -p "Your prompt here"
```
This mode:
* **Skips interactive prompts** - Returns error if auth needed
* **Uses default profile** - Or specify with first arg: `ccs codex -p "prompt"`
* **Outputs to stdout** - JSON-parsable responses
* **Exits with code** - 0 = success, non-zero = failure
## Prerequisites
* CCS installed on CI runner
* Initial authentication done (see Step 1)
* Session files accessible to CI environment
**You cannot authenticate directly in CI** - OAuth requires browser.
On your local machine:
```bash theme={null}
ccs codex --auth
```
This creates session files in `~/.ccs/cliproxy/`:
* `sessions.json` - Session metadata
* `gemini-{account}.json` - OAuth tokens
**Session expiry:** 7 days from last token refresh.
**Option A: GitHub Actions Secrets**
Base64-encode session files:
```bash theme={null}
# On local machine
tar -czf ccs-sessions.tar.gz -C ~/.ccs/cliproxy sessions.json gemini-*.json
base64 ccs-sessions.tar.gz > ccs-sessions.b64
```
Add to GitHub secrets:
* Go to repo Settings → Secrets → Actions
* Create secret `CCS_SESSIONS` with contents of `ccs-sessions.b64`
**Option B: GitLab CI Variables**
```bash theme={null}
# Add as file-type CI/CD variable
cat ccs-sessions.tar.gz | base64
```
Settings → CI/CD → Variables → Add variable:
* Key: `CCS_SESSIONS`
* Type: File
* Value: (paste base64 content)
**Option C: Self-Hosted Runner**
Copy directly to runner home:
```bash theme={null}
scp -r ~/.ccs/cliproxy runner-host:~/.ccs/
```
**GitHub Actions:**
```yaml theme={null}
- name: Setup CCS Sessions
run: |
mkdir -p ~/.ccs/cliproxy
echo "${{ secrets.CCS_SESSIONS }}" | base64 -d | tar -xzf - -C ~/.ccs/cliproxy
```
**GitLab CI:**
```yaml theme={null}
before_script:
- mkdir -p ~/.ccs/cliproxy
- base64 -d $CCS_SESSIONS | tar -xzf - -C ~/.ccs/cliproxy
```
**Docker:**
```dockerfile theme={null}
COPY ccs-sessions.tar.gz /tmp/
RUN mkdir -p ~/.ccs/cliproxy && \
tar -xzf /tmp/ccs-sessions.tar.gz -C ~/.ccs/cliproxy && \
rm /tmp/ccs-sessions.tar.gz
```
**GitHub Actions Example:**
```yaml theme={null}
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install CCS
run: npm install -g @kaitranntt/ccs@latest
- name: Setup Sessions
run: |
mkdir -p ~/.ccs/cliproxy
echo "${{ secrets.CCS_SESSIONS }}" | base64 -d | tar -xzf - -C ~/.ccs/cliproxy
- name: Run AI Review
run: |
ccs codex -p "Review the changes in this PR and suggest improvements" > review.txt
- name: Post Comment
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const review = fs.readFileSync('review.txt', 'utf8');
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: review
});
```
**GitLab CI Example:**
```yaml theme={null}
review:
stage: test
image: node:20
before_script:
- npm install -g @kaitranntt/ccs@latest
- mkdir -p ~/.ccs/cliproxy
- base64 -d $CCS_SESSIONS | tar -xzf - -C ~/.ccs/cliproxy
script:
- ccs codex -p "Analyze code quality and suggest refactorings" | tee review.txt
artifacts:
paths:
- review.txt
```
Sessions expire after 7 days. Options:
**Option A: Scheduled Re-Authentication**
Create GitHub Action that runs weekly:
```yaml theme={null}
name: Refresh CCS Sessions
on:
schedule:
- cron: '0 0 * * 0' # Every Sunday
workflow_dispatch: # Manual trigger
jobs:
refresh:
runs-on: self-hosted # Must have browser
steps:
- name: Re-authenticate
run: |
ccs codex --auth # Opens browser on self-hosted runner
- name: Archive Sessions
run: |
cd ~/.ccs/cliproxy
tar -czf ccs-sessions.tar.gz sessions.json gemini-*.json
base64 ccs-sessions.tar.gz
- name: Update Secret
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh secret set CCS_SESSIONS < ccs-sessions.tar.gz
```
**Option B: Check and Exit Gracefully**
```bash theme={null}
#!/bin/bash
ccs codex -p "Test prompt" || {
echo "[!] CCS session expired. Please re-authenticate locally and update CI secrets."
exit 1
}
```
**Option C: Remote Proxy (Recommended)**
Use [Remote Proxy](/tutorials/remote-proxy-deployment) to centralize auth on server.
Control behavior via env vars:
```yaml theme={null}
env:
CCS_DEBUG: "0" # Disable debug logs in CI
CCS_SKIP_PREFLIGHT: "1" # Skip API key validation
CCS_WEBSEARCH_SKIP: "1" # Disable WebSearch hook
CCS_PROXY_FALLBACK_ENABLED: "0" # Fail fast if proxy down
DISABLE_TELEMETRY: "1" # Disable telemetry
DISABLE_ERROR_REPORTING: "1" # Disable error reporting
```
**Security tip:** Never log `CCS_PROXY_AUTH_TOKEN` in CI output.
Headless mode outputs raw AI response. Parse for CI:
```bash theme={null}
# Extract JSON from response
ccs codex -p "Analyze this code and return JSON: {score: number, issues: string[]}" | \
jq -r '.score'
# Fail pipeline if score below threshold
SCORE=$(ccs albb -p "Rate code quality 1-10" | grep -oE '[0-9]+' | head -1)
if [ "$SCORE" -lt 7 ]; then
echo "[X] Code quality score $SCORE below threshold"
exit 1
fi
```
**Example: Extract action items**
```bash theme={null}
ccs codex -p "List action items from meeting notes in MEETING.md" | \
grep -E '^\s*[-*]' > action-items.txt
```
## Complete CI/CD Examples
### GitHub Actions: Automated Documentation
```yaml theme={null}
name: Generate Docs
on:
push:
branches: [main]
paths:
- 'src/**'
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install CCS
run: npm install -g @kaitranntt/ccs@latest
- name: Setup Sessions
run: |
mkdir -p ~/.ccs/cliproxy
echo "${{ secrets.CCS_SESSIONS }}" | base64 -d | tar -xzf - -C ~/.ccs/cliproxy
- name: Generate API Docs
run: |
ccs codex -p "Generate API documentation from src/ directory in Markdown format" > docs/api.md
- name: Commit Docs
run: |
git config user.name "AI Docs Bot"
git config user.email "bot@example.com"
git add docs/api.md
git commit -m "docs: update API documentation [skip ci]" || exit 0
git push
```
### GitLab CI: Code Quality Gate
```yaml theme={null}
stages:
- test
- review
quality-check:
stage: test
image: node:20
before_script:
- npm install -g @kaitranntt/ccs@latest
- mkdir -p ~/.ccs/cliproxy
- base64 -d $CCS_SESSIONS | tar -xzf - -C ~/.ccs/cliproxy
script:
- |
ccs albb -p "Analyze code in src/ and rate quality 1-10. Output only the number." > score.txt
SCORE=$(cat score.txt | grep -oE '[0-9]+' | head -1)
echo "Code quality score: $SCORE/10"
if [ "$SCORE" -lt 7 ]; then
echo "Quality gate failed: score below 7"
exit 1
fi
only:
- merge_requests
```
### Jenkins: Nightly Analysis
```groovy theme={null}
pipeline {
agent any
triggers {
cron('H 2 * * *') // 2 AM daily
}
environment {
CCS_DEBUG = '0'
CCS_SKIP_PREFLIGHT = '1'
}
stages {
stage('Setup') {
steps {
sh 'npm install -g @kaitranntt/ccs@latest'
sh 'mkdir -p ~/.ccs/cliproxy'
withCredentials([file(credentialsId: 'ccs-sessions', variable: 'SESSIONS_FILE')]) {
sh 'tar -xzf $SESSIONS_FILE -C ~/.ccs/cliproxy'
}
}
}
stage('Analyze') {
steps {
sh '''
ccs codex -p "Analyze codebase for security vulnerabilities and performance issues" > report.md
'''
}
}
stage('Publish') {
steps {
archiveArtifacts artifacts: 'report.md'
emailext(
subject: "Nightly Code Analysis Report",
body: readFile('report.md'),
to: 'dev-team@example.com'
)
}
}
}
}
```
## Environment Variables Reference
| Variable | Default | Purpose |
| ---------------------------- | ------- | ------------------------ |
| `CCS_DEBUG` | `0` | Enable verbose logging |
| `CCS_SKIP_PREFLIGHT` | `0` | Skip API key validation |
| `CCS_WEBSEARCH_SKIP` | `0` | Disable WebSearch hook |
| `CCS_PROXY_FALLBACK_ENABLED` | `1` | Fallback to local proxy |
| `CCS_UNIFIED_CONFIG` | `1` | Use unified config mode |
| `CCS_MIGRATE` | `0` | Trigger auto-migration |
| `DISABLE_TELEMETRY` | unset | Disable Claude telemetry |
| `DISABLE_ERROR_REPORTING` | unset | Disable error reporting |
| `DISABLE_BUG_COMMAND` | unset | Disable bug reporting |
## Troubleshooting
### Authentication Required
**Symptom:** `[X] Auth error: No valid session found`
**Causes:**
* Sessions not restored correctly
* Session files expired (>7 days)
* Wrong provider in headless command
**Solutions:**
```bash theme={null}
# Verify session files exist
ls -la ~/.ccs/cliproxy/sessions.json
# Check session age
stat -c %y ~/.ccs/cliproxy/sessions.json
# Re-authenticate locally and update CI secrets
```
### Token Refresh Failed
**Symptom:** `[X] Network error: UND_ERR_SOCKET`
**Causes:**
* Firewall blocking OAuth endpoints
* Proxy configuration issues
* Network timeout
**Solutions:**
```bash theme={null}
# Increase timeout
export CCS_PROXY_TIMEOUT=5000
# Check network access
curl -I https://auth.openai.com
```
### Session File Permissions
**Symptom:** `[X] Config error: EACCES`
**Cause:** Session files not readable by CI user
**Solution:**
```bash theme={null}
chmod 600 ~/.ccs/cliproxy/sessions.json
chmod 600 ~/.ccs/cliproxy/*.json
```
### Prompt Too Long
**Symptom:** Command line argument limit exceeded
**Solution:** Use file redirection:
```bash theme={null}
# Instead of:
ccs codex -p "$(cat large-file.txt)"
# Use:
ccs codex -p "Analyze the content of large-file.txt" < large-file.txt
```
## Security Best Practices
### Protect Session Files
* **Encrypt in transit:** Use secrets/variables, not environment variables
* **Rotate regularly:** Re-authenticate every 7 days maximum
* **Scope access:** Limit CI job permissions to necessary secrets
* **Audit logs:** Monitor secret access in GitHub/GitLab audit logs
### Minimize Token Exposure
```yaml theme={null}
# ❌ BAD: Token in logs
- run: echo "Token: ${{ secrets.CCS_SESSIONS }}"
# ✅ GOOD: Silent extraction
- run: echo "${{ secrets.CCS_SESSIONS }}" | base64 -d | tar -xzf - -C ~/.ccs/cliproxy
```
### Use Self-Hosted Runners
For sensitive repos, use self-hosted runners:
* Sessions stay on your infrastructure
* No need to upload to GitHub secrets
* Easier re-authentication workflow
## Next Steps
Centralize auth on server, avoid session expiry issues
Deep dive into session persistence and refresh logic
# Multi-Account Setup
Source: https://docs.ccs.kaitran.ca/tutorials/multi-account-setup
Set up work and personal Claude accounts with CCS
## Overview
CCS supports multiple accounts per OAuth provider (Gemini, Codex, Antigravity, etc.), enabling you to:
* Work around rate limits by switching accounts
* Separate personal and work usage
* Test with different quota tiers
* Organize projects by account
Want several Claude accounts to **auto-continue** for you when one hits its
limit, instead of switching by hand? See [Account Pools](/features/pool). This
page covers manual per-account management; pools add automatic failover for the
built-in `claude` provider.
## Prerequisites
* CCS CLI installed
* OAuth provider configured (gemini, codex, agy, iflow, kiro, kimi, ghcp)
* Browser for OAuth flow
Run authentication for the provider:
```bash theme={null}
ccs codex --auth
```
This opens your browser for OAuth. After authorizing, CCS stores the token and assigns a default nickname (your email).
**Note:** First account becomes the default for that provider.
Use the `--add` flag with `--auth` to add another account:
```bash theme={null}
ccs codex --add --auth
```
CCS detects this as a new account and:
* Opens browser for second OAuth flow
* Stores token separately from first account
* Updates `~/.ccs/cliproxy/accounts.json` registry
**Tip:** You can add unlimited accounts per provider.
View registered accounts:
```bash theme={null}
ccs codex --accounts
```
Output shows:
* Account nicknames (email or custom name)
* Default account marker
* Last used timestamp
Example output:
```
[i] Gemini accounts:
* user@gmail.com (default) - Last used: 2026-01-05
work@company.com - Last used: 2026-01-03
```
Change which account is used by default:
```bash theme={null}
ccs codex --use work@company.com
```
This updates the default in `config.yaml` under `cliproxy.variants.gemini.account`.
**Note:** Switching only affects future sessions, not active ones.
Override default without changing config:
```bash theme={null}
ccs codex --use work@company.com "Analyze this codebase"
```
This session uses `work@company.com`, but next time defaults to configured account.
Make accounts easier to identify:
```bash theme={null}
ccs codex --nickname personal --use user@gmail.com
ccs codex --nickname work --use work@company.com
```
Now you can reference accounts by nickname:
```bash theme={null}
ccs codex --use personal
ccs codex --accounts
# Output: personal (user@gmail.com), work (work@company.com)
```
Remove an account:
```bash theme={null}
ccs codex --logout --use work@company.com
```
This:
* Revokes OAuth token
* Removes from `accounts.json`
* Prompts to set new default if removing default account
## Understanding Account Storage
### Registry File: `~/.ccs/cliproxy/accounts.json`
```json theme={null}
{
"gemini": {
"personal": {
"email": "user@gmail.com",
"tokenPath": "~/.ccs/cliproxy/gemini-personal.json",
"createdAt": "2026-01-05T10:30:00Z",
"lastUsed": "2026-01-05T14:20:00Z"
},
"work": {
"email": "work@company.com",
"tokenPath": "~/.ccs/cliproxy/gemini-work.json",
"createdAt": "2026-01-03T09:15:00Z",
"lastUsed": "2026-01-03T18:45:00Z"
}
}
}
```
### Config Reference: `~/.ccs/config.yaml`
```yaml theme={null}
cliproxy:
oauth_accounts:
personal: user@gmail.com
work: work@company.com
variants:
gemini:
account: personal # Default account
```
## Common Use Cases
### Scenario 1: Rate Limit Rotation
If you hit quota limits, switch to another account:
```bash theme={null}
# Primary account hits limit
ccs codex "Complex task"
# Error: Rate limit exceeded
# Switch to secondary
ccs codex --use secondary "Complex task"
# Success
```
### Scenario 2: Separate Work/Personal
Keep projects isolated:
```bash theme={null}
# Work project
ccs codex --use work
# Personal project
ccs codex --use personal
```
### Scenario 3: Testing Different Tiers
Compare behavior across quota tiers:
```bash theme={null}
# Free tier account
ccs codex --use standard-tier "Test request"
# Paid tier account
ccs codex --use premium-tier "Test request"
```
## Troubleshooting
### Account Not Found
**Error:** `Account 'xyz' not found for gemini`
**Solution:** List accounts to verify name:
```bash theme={null}
ccs codex --accounts
```
### Default Account Not Set
**Error:** `No default account configured`
**Solution:** Set default explicitly:
```bash theme={null}
ccs codex --use your-email@example.com
```
### Token Expired
CCS automatically refreshes OAuth tokens 5 minutes before expiry. If manual refresh needed:
```bash theme={null}
ccs codex --auth --use expired-account
```
## Next Steps
Learn about token refresh, session files, and troubleshooting
Deploy CLIProxy on remote server for team sharing
# Remote Proxy Deployment
Source: https://docs.ccs.kaitran.ca/tutorials/remote-proxy-deployment
Deploy CLIProxy to a remote server for team access
## Overview
Remote proxy deployment allows you to:
* **Centralize OAuth tokens** - Team shares one authenticated server
* **Bypass network restrictions** - Route through server with API access
* **Reduce client setup** - No local binary installation needed
* **Monitor usage centrally** - Track all requests through proxy
## Architecture
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ CCS Client │ HTTPS │ Remote Proxy │ OAuth │ AI Provider │
│ (Laptop A) ├─────────▶│ Server ├─────────▶│ (Gemini) │
└─────────────┘ │ │ └─────────────┘
│ Port 443 │
┌─────────────┐ │ or 80 │
│ CCS Client │ HTTPS │ │
│ (Laptop B) ├─────────▶│ │
└─────────────┘ └──────────────┘
```
## Prerequisites
* Linux server with public IP or domain
* Root/sudo access for port binding (80/443)
* CCS CLI installed locally
* Basic understanding of systemd (for persistent service)
SSH into your server and install CCS:
```bash theme={null}
ssh user@your-server.com
npm install -g @kaitranntt/ccs@latest
```
Verify installation:
```bash theme={null}
ccs --version
```
**Note:** Server doesn't need Claude Code installed, only CCS CLI.
Create `~/.ccs/config.yaml` on server:
```yaml theme={null}
version: 6
cliproxy:
auth:
api_key: "your-secure-api-key-here"
management_secret: "your-management-secret-here"
providers:
- gemini
- codex
- agy
cliproxy_server:
local:
port: 8317
auto_start: true
```
**Security:** Generate strong random keys:
```bash theme={null}
# Generate API key
openssl rand -base64 32
# Generate management secret
openssl rand -base64 32
```
On the server, authenticate each provider:
```bash theme={null}
ccs codex --auth
ccs kimi --auth
ccs kiro --auth
```
**Important:** Server needs a browser for OAuth flow. Options:
* SSH with X11 forwarding: `ssh -X user@server`
* Use `--import` flag (Kiro only) to copy token from local machine
* Temporarily run on desktop, copy `~/.ccs/cliproxy/*.json` to server
Create service file `/etc/systemd/system/ccs-proxy.service`:
```ini theme={null}
[Unit]
Description=CCS CLIProxy Server
After=network.target
[Service]
Type=simple
User=your-user
WorkingDirectory=/home/your-user
ExecStart=/usr/bin/node /usr/lib/node_modules/@kaitranntt/ccs/dist/cliproxy-server.js
Restart=on-failure
RestartSec=10
Environment="PORT=8317"
Environment="CCS_PROXY_AUTH_TOKEN=your-secure-api-key-here"
[Install]
WantedBy=multi-user.target
```
Enable and start:
```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable ccs-proxy
sudo systemctl start ccs-proxy
sudo systemctl status ccs-proxy
```
Use nginx for HTTPS termination:
```nginx theme={null}
server {
listen 443 ssl http2;
server_name ccs.your-domain.com;
ssl_certificate /etc/letsencrypt/live/ccs.your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/ccs.your-domain.com/privkey.pem;
location / {
proxy_pass http://localhost:8317;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
**Obtain SSL certificate:**
```bash theme={null}
sudo certbot --nginx -d ccs.your-domain.com
```
On your local machine, edit `~/.ccs/config.yaml`:
```yaml theme={null}
version: 6
cliproxy_server:
remote:
enabled: true
host: "ccs.your-domain.com"
port: 443
protocol: "https"
auth_token: "your-secure-api-key-here"
management_key: "your-management-secret-here" # Optional
timeout: 2000 # ms
fallback:
enabled: true # Fallback to local if remote unreachable
auto_start: false
```
**Alternative:** Use CLI flags:
```bash theme={null}
export CCS_PROXY_HOST="ccs.your-domain.com"
export CCS_PROXY_PORT="443"
export CCS_PROXY_AUTH_TOKEN="your-secure-api-key-here"
export CCS_PROXY_PROTOCOL="https"
```
Verify client can reach remote proxy:
```bash theme={null}
ccs codex "Hello from remote proxy"
```
Check logs on server:
```bash theme={null}
sudo journalctl -u ccs-proxy -f
```
Expected output:
```
[i] Request from 203.0.113.45: codex
[OK] Response sent: 200
```
Control what happens if remote fails:
**Fail Fast (No Fallback):**
```bash theme={null}
ccs codex --remote-only "Task"
```
Exits with error if remote unreachable.
**Force Local (Skip Remote):**
```bash theme={null}
ccs codex --local-proxy "Task"
```
Uses local proxy even if remote configured.
**Graceful Degradation (Default):**
```yaml theme={null}
cliproxy_server:
fallback:
enabled: true
auto_start: true # Auto-start local on remote failure
```
## Configuration Reference
### Corporate Proxy Support
CCS respects standard system proxy environment variables for binary downloads and network requests:
| Variable | Purpose | Example |
| ----------------------------- | --------------------------- | ----------------------------------- |
| `http_proxy` / `HTTP_PROXY` | HTTP proxy server | `http://proxy.corp.com:8080` |
| `https_proxy` / `HTTPS_PROXY` | HTTPS proxy server | `http://proxy.corp.com:8080` |
| `NO_PROXY` | Comma-separated bypass list | `localhost,127.0.0.1,.internal.com` |
**Use case:** When downloading CLIProxy binary or making outbound requests from behind a corporate firewall.
```bash theme={null}
# Set system proxy before running CCS
export http_proxy=http://proxy.corp.com:8080
export https_proxy=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1
ccs cliproxy update # Will use proxy for binary download
```
**Note:** These variables are for outbound network access. For CLIProxy *server* configuration, use the CCS-specific variables below.
### CCS Environment Variables
| Variable | Purpose | Example |
| ---------------------------- | -------------------- | ---------------------------- |
| `CCS_PROXY_HOST` | Remote hostname | `proxy.company.com` |
| `CCS_PROXY_PORT` | Remote port | `443` (HTTPS) or `80` (HTTP) |
| `CCS_PROXY_AUTH_TOKEN` | API authentication | `base64-encoded-key` |
| `CCS_PROXY_PROTOCOL` | Protocol | `https` or `http` |
| `CCS_PROXY_TIMEOUT` | Health check timeout | `2000` (ms) |
| `CCS_PROXY_FALLBACK_ENABLED` | Enable fallback | `true` or `false` |
### CLI Flags
| Flag | Description |
| -------------------------------- | -------------------------- |
| `--proxy-host ` | Override config host |
| `--proxy-port ` | Override config port |
| `--proxy-auth-token ` | Override config token |
| `--proxy-protocol ` | Override protocol |
| `--proxy-timeout ` | Health check timeout |
| `--remote-only` | Fail if remote unavailable |
| `--local-proxy` | Force local, skip remote |
| `--allow-self-signed` | Accept self-signed certs |
### Config Priority
1. **CLI flags** (highest priority)
2. **Environment variables**
3. **config.yaml**
4. **Defaults** (lowest priority)
## Security Best Practices
### Authentication
* **Rotate keys regularly** - Update `api_key` and `management_secret` quarterly
* **Use different keys** - Separate `auth_token` and `management_key`
* **Limit scope** - `api_key` for queries, `management_key` for admin operations
### Network Security
* **Use HTTPS** - Always in production (self-signed OK for internal networks)
* **Firewall rules** - Restrict proxy port to known IPs:
```bash theme={null}
sudo ufw allow from 203.0.113.0/24 to any port 443
```
* **VPN recommended** - Route traffic through VPN for extra security
### Monitoring
* **Log all requests** - Enable in config:
```yaml theme={null}
cliproxy:
logging:
enabled: true
request_log: true
```
* **Monitor disk usage** - Logs can grow large, rotate with logrotate
* **Track quotas** - Use `/api/usage/summary` endpoint
## Troubleshooting
### Connection Refused
**Symptom:** `[X] Proxy error: ECONNREFUSED`
**Causes:**
* Server not running: `sudo systemctl status ccs-proxy`
* Firewall blocking: `sudo ufw status`
* Wrong port in config
### Authentication Failed
**Symptom:** `[X] Auth error: Invalid token`
**Causes:**
* Token mismatch between client and server
* Token expired (server restarted with new config)
**Solution:** Verify tokens match:
```bash theme={null}
# Server
grep api_key ~/.ccs/config.yaml
# Client
grep auth_token ~/.ccs/config.yaml
```
### SSL Certificate Errors
**Symptom:** `[X] Network error: UNABLE_TO_VERIFY_LEAF_SIGNATURE`
**Solutions:**
```bash theme={null}
# Accept self-signed (development only)
ccs codex --allow-self-signed "Task"
# Or set in config:
export CCS_ALLOW_SELF_SIGNED=true
```
### Fallback Not Working
**Symptom:** Remote fails but local doesn't start
**Causes:**
* `fallback.enabled: false` in config
* `fallback.auto_start: false` and local binary missing
**Solution:**
```yaml theme={null}
cliproxy_server:
fallback:
enabled: true
auto_start: true # Auto-download binary if missing
```
## Advanced Configuration
### Multi-Region Deployment
**Planned Feature** - Multi-region auto-selection is not yet implemented. This configuration syntax is reserved for future use.
Deploy proxies in different regions, clients auto-select fastest:
```yaml theme={null}
cliproxy_server:
remote:
hosts:
- host: "us-east.proxy.com"
region: "us-east"
- host: "eu-west.proxy.com"
region: "eu-west"
auto_select: true # Ping-based selection
```
### Load Balancing
Use nginx upstream for multiple proxy instances:
```nginx theme={null}
upstream ccs_proxy {
least_conn;
server 127.0.0.1:8317;
server 127.0.0.1:8318;
server 127.0.0.1:8319;
}
server {
location / {
proxy_pass http://ccs_proxy;
}
}
```
## Next Steps
Manage multiple OAuth accounts on the proxy server
Understand token refresh and session persistence
# Token Management
Source: https://docs.ccs.kaitran.ca/tutorials/token-management
Manage OAuth tokens, API keys, and credentials across CCS profiles
## Overview
CCS implements sophisticated token management to provide seamless authentication:
* **Proactive Refresh** - Tokens renewed 5min before expiry (no interruptions)
* **Session Persistence** - Reference counting tracks active sessions
* **Automatic Recovery** - Handles network errors, token expiry gracefully
* **Multi-Account Support** - Separate tokens per account
## Token Lifecycle
### OAuth Flow (Initial Authentication)
```
┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐
│ ccs CLI │────▶│ Browser │────▶│ Provider │────▶│ Consent │
└─────────┘ └─────────┘ │ OAuth │ │ Page │
▲ └──────────┘ └─────────┘
│ │
│ Access Token │
│ + Refresh Token │
└─────────────────────────────────┘
```
**Files Created:**
* `~/.ccs/cliproxy/gemini-{account}.json` - Access + refresh tokens
* `~/.ccs/cliproxy/sessions.json` - Session metadata
### Proactive Token Refresh
CCS checks token expiry **before every request**:
```
Token expires at: 14:00:00
Current time: 13:54:00
Time remaining: 6 minutes
Action: Refresh now (threshold: 5 minutes)
```
**Why 5 minutes?**
* Accounts for network latency
* Prevents mid-request expiry
* Ensures smooth user experience
**Refresh Process:**
1. Send refresh\_token to provider
2. Receive new access\_token (expires in 1 hour)
3. Receive new refresh\_token (expires in 7 days)
4. Update `{provider}-{account}.json`
5. Continue with original request
## Session Persistence
### Session Files
**Location:** `~/.ccs/cliproxy/sessions.json`
**Structure:**
```json theme={null}
{
"gemini": {
"primary": {
"email": "user@gmail.com",
"tokenPath": "~/.ccs/cliproxy/gemini-primary.json",
"expiresAt": "2026-01-12T14:00:00Z",
"refreshedAt": "2026-01-05T13:55:00Z",
"referenceCount": 2,
"lastError": null
}
}
}
```
**Key Fields:**
| Field | Purpose |
| ---------------- | ------------------------------------------ |
| `expiresAt` | Access token expiry (1 hour from issue) |
| `refreshedAt` | Last refresh timestamp |
| `referenceCount` | Number of active sessions using this token |
| `lastError` | Most recent error (for debugging) |
### Reference Counting
**Purpose:** Track multiple active CCS sessions reusing the same CLIProxy proxy/session state
**How it works:**
```bash theme={null}
# Terminal 1
ccs codex "Task 1" # referenceCount: 1
# Terminal 2 (while Terminal 1 running)
ccs codex "Task 2" # referenceCount: 2
# Terminal 1 completes
# referenceCount: 1
# Terminal 2 completes
# referenceCount: 0
```
**Why it matters:**
* Prevents premature token cleanup
* Supports shared proxy sessions without tearing down token state too early
* Tracks active usage
This is not the same thing as full per-session isolation. Multiple sessions
can reuse the same CLIProxy session/proxy state while still sharing provider
runtime state.
### Session Cleanup
**Automatic cleanup when:**
* `referenceCount` reaches 0
* Session idle for >7 days
* Manual logout via `ccs codex --logout`
**Cleanup process:**
1. Revoke refresh token with provider
2. Delete token file
3. Remove from `sessions.json`
4. Update `accounts.json` registry
## File Structure
### Token Files
**Per-account token storage:**
```bash theme={null}
~/.ccs/cliproxy/
├── gemini-primary.json # First account tokens
├── gemini-work.json # Second account tokens
├── codex-default.json # Codex tokens
└── agy-enterprise.json # Antigravity tokens
```
**Token file format:**
```json theme={null}
{
"access_token": "ya29.a0AfB...",
"refresh_token": "1//0gZ...",
"expires_at": 1704463200000,
"token_type": "Bearer",
"scope": "email profile openid"
}
```
### Account Registry
**Location:** `~/.ccs/cliproxy/accounts.json`
**Purpose:** Map nicknames to email addresses
```json theme={null}
{
"gemini": {
"primary": {
"email": "user@gmail.com",
"tokenPath": "~/.ccs/cliproxy/gemini-primary.json",
"createdAt": "2026-01-01T10:00:00Z",
"lastUsed": "2026-01-05T14:30:00Z"
},
"work": {
"email": "work@company.com",
"tokenPath": "~/.ccs/cliproxy/gemini-work.json",
"createdAt": "2026-01-03T09:00:00Z",
"lastUsed": "2026-01-05T11:15:00Z"
}
}
}
```
### Config Reference
**Location:** `~/.ccs/config.yaml`
**Relevant sections:**
```yaml theme={null}
cliproxy:
oauth_accounts:
primary: user@gmail.com
work: work@company.com
variants:
gemini:
account: primary # Default account for gemini
```
## Manual Token Operations
Use the `tokens` command to inspect current state:
```bash theme={null}
ccs tokens
```
**Output:**
```
[i] OAuth Token Status
Gemini:
primary (user@gmail.com)
Status: Valid
Expires: 2026-01-05 15:30:00 (in 25 minutes)
Last Refreshed: 2026-01-05 14:25:00
Active Sessions: 1
work (work@company.com)
Status: Valid
Expires: 2026-01-05 16:00:00 (in 55 minutes)
Last Refreshed: 2026-01-05 14:50:00
Active Sessions: 0
Codex:
default (dev@example.com)
Status: Expired
Expires: 2026-01-05 13:00:00 (1 hour ago)
Last Refreshed: 2026-01-05 12:00:00
Active Sessions: 0
Note: Will auto-refresh on next use
```
Manually trigger refresh without waiting for threshold:
```bash theme={null}
ccs tokens --refresh gemini
```
**Use cases:**
* Debugging refresh issues
* Pre-warming tokens before long task
* Recovering from network errors
Remove tokens that can't be refreshed:
```bash theme={null}
ccs tokens --cleanup
```
This removes:
* Tokens expired >7 days (refresh token expired)
* Tokens with persistent errors
* Orphaned session entries
For migration or backup:
```bash theme={null}
ccs tokens --export gemini > gemini-backup.json
```
**Security warning:** Exported files contain sensitive tokens. Encrypt before storage:
```bash theme={null}
gpg -c gemini-backup.json
rm gemini-backup.json
```
Restore from backup or migrate between machines:
```bash theme={null}
# Decrypt first
gpg -d gemini-backup.json.gpg > gemini-backup.json
# Import
ccs tokens --import gemini < gemini-backup.json
# Clean up
shred -u gemini-backup.json
```
**Note:** Only works for same provider. Cross-provider imports not supported.
## Troubleshooting
### UND\_ERR\_SOCKET Error
**Full error:**
```
[X] Network error: UND_ERR_SOCKET - The socket connection was aborted
```
**Common causes:**
1. **Network interruption during refresh**
```bash theme={null}
# Check if provider auth endpoint is reachable
curl -I https://auth.openai.com
# Force new auth flow
ccs codex --auth
```
2. **Proxy interference**
```bash theme={null}
# Bypass proxy for OAuth
unset HTTP_PROXY HTTPS_PROXY
# Re-authenticate
ccs codex --auth
```
3. **Firewall blocking OAuth endpoints**
```bash theme={null}
# Test connectivity
curl -v https://auth.openai.com/authorize
# Whitelist required domains:
# - auth.openai.com
```
4. **Concurrent refresh attempts**
* Multiple sessions trying to refresh simultaneously
* Session files locked by another process
**Solution:**
```bash theme={null}
# Wait a few seconds and retry
sleep 5 && ccs codex "Task"
```
### Token Refresh Fails
**Symptom:** `[X] Auth error: Failed to refresh token`
**Causes:**
1. **Refresh token expired (>7 days)**
```bash theme={null}
# Check session age
stat ~/.ccs/cliproxy/sessions.json
# Re-authenticate
ccs codex --auth
```
2. **Provider revoked access**
* User revoked app permissions
* Provider detected suspicious activity
**Solution:**
```bash theme={null}
# Clear old tokens
ccs codex --logout
# Fresh authentication
ccs codex --auth
```
3. **Clock skew**
```bash theme={null}
# Sync system time
sudo ntpdate pool.ntp.org
# Or manually set timezone
sudo timedatectl set-timezone America/New_York
```
### Session File Corruption
**Symptom:** `[X] Config error: Failed to parse sessions.json`
**Recovery steps:**
```bash theme={null}
# Backup corrupted file
cp ~/.ccs/cliproxy/sessions.json ~/.ccs/cliproxy/sessions.json.backup
# Remove corrupted file
rm ~/.ccs/cliproxy/sessions.json
# Re-authenticate (recreates session file)
ccs codex --auth
```
**Prevention:** Enable debug logging to catch issues early:
```bash theme={null}
export CCS_DEBUG=1
ccs codex "Test"
```
### Multiple Accounts Conflict
**Symptom:** Wrong account used despite `--use` flag
**Cause:** Default account set in config overrides flag
**Solution:**
```bash theme={null}
# Verify default account
grep -A5 "variants:" ~/.ccs/config.yaml
# Update default permanently
ccs codex --use correct-account
# Or override per-session
ccs codex --use correct-account "Task"
```
### Token Not Found After Re-Auth
**Symptom:** `[X] Profile error: Account 'xyz' not found`
**Cause:** Account registry out of sync with token files
**Solution:**
```bash theme={null}
# Rebuild account registry
ccs tokens --rebuild
# Or manually verify files
ls -la ~/.ccs/cliproxy/*.json
cat ~/.ccs/cliproxy/accounts.json
```
## Advanced Patterns
### Pre-Warming Tokens
For long-running tasks, refresh tokens before starting:
```bash theme={null}
#!/bin/bash
# Pre-warm all accounts
ccs tokens --refresh gemini
ccs tokens --refresh codex
# Now run long task without interruption
ccs codex "Analyze entire codebase in /project"
```
### Monitoring Token Health
Create a cron job to check token status:
```bash theme={null}
#!/bin/bash
# check-tokens.sh
STATUS=$(ccs tokens --json)
EXPIRED=$(echo "$STATUS" | jq -r '.[] | select(.status == "expired") | .account')
if [ -n "$EXPIRED" ]; then
echo "⚠️ Expired tokens detected: $EXPIRED"
# Send notification
curl -X POST https://hooks.slack.com/... -d "{\"text\": \"CCS tokens expired: $EXPIRED\"}"
fi
```
```cron theme={null}
# Crontab entry (check daily at 9 AM)
0 9 * * * /path/to/check-tokens.sh
```
### Shared Team Tokens
For teams using [Remote Proxy](/tutorials/remote-proxy-deployment):
**On server:**
```bash theme={null}
# Authenticate with team account
ccs codex --auth --nickname team-codex
# Verify token valid
ccs tokens --refresh team-codex
```
**Clients automatically inherit server's tokens** - no local auth needed.
## Environment Variables
| Variable | Purpose | Example |
| ---------------------------- | -------------------------------- | ------------------------------------- |
| `CCS_DEBUG` | Show token refresh logs | `export CCS_DEBUG=1` |
| `CCS_SKIP_PREFLIGHT` | Skip token validation | `export CCS_SKIP_PREFLIGHT=1` |
| `CCS_PROXY_FALLBACK_ENABLED` | Fallback behavior on token error | `export CCS_PROXY_FALLBACK_ENABLED=0` |
## Security Best Practices
### Protect Token Files
```bash theme={null}
# Set restrictive permissions
chmod 600 ~/.ccs/cliproxy/*.json
# Prevent accidental commits
echo "*.json" >> ~/.ccs/.gitignore
```
### Rotate Tokens Regularly
```bash theme={null}
# Logout all accounts
ccs codex --logout
ccs kimi --logout
# Re-authenticate with fresh tokens
ccs codex --auth
ccs kimi --auth
```
**Recommended:** Rotate every 30 days, or immediately if compromise suspected.
### Monitor Token Usage
Enable request logging to track token usage:
```yaml theme={null}
# ~/.ccs/config.yaml
cliproxy:
logging:
enabled: true
request_log: true
```
**Logs location:** `~/.ccs/logs/cliproxy-requests.log`
## Next Steps
Configure and switch between multiple accounts
Use persistent sessions in automation workflows