Claude Code Switch (CCS)

CCS Bar is a native SwiftUI menu bar application for macOS that acts as a thin client for the CCS local web-server. It allows users to monitor per-account quota, cost, and tier, and perform account control actions directly from the menu bar, such as:

• Pause/Resume
• Set default account
• Solo an account
• Tier-lock

Important Security Note: The app never communicates with providers directly. All requests are routed through localhost to the CCS server, which handles provider fetches server-side.

The CCS Dashboard (ui/) uses i18next and react-i18next for internationalization.

Supported Locales:

• en (English) - Default fallback
• zh-CN (Simplified Chinese)
• vi (Vietnamese)
• ja (Japanese)

Technical Details:

• Persistence: Locale selection is stored in browser localStorage under the key ccs-ui-locale.
• Initialization: The i18n instance is initialized in ui/src/App.tsx via import '@/lib/i18n' before routes render.
• Core Utilities:
  • normalizeLocale(locale): Maps values to supported app locales.
  • getInitialLocale(): Determines locale from storage, then browser, then en.
  • persistLocale(): Writes the normalized locale to localStorage.

Note: i18n currently only covers React UI text. It does not cover CLI terminal output or Backend/API payloads.

CCS maintains a strict security hierarchy to protect user credentials and data. The communication flow is structured as follows:

1. User Terminal: Local only, no network exposure.
2. CCS CLI: Communicates via localhost (127.0.0.1) only.
3. CLIProxy/Legacy: Binds to localhost only and uses TLS encryption.
4. Target CLI: (e.g., claude or droid) Spawned locally and uses TLS encryption.
5. Provider APIs: External endpoints reached via the target CLI.

CCS uses hybrid quota management to automatically detect exhausted accounts and failover to the next available account.

How it works:

1. Pre-flight Check: Before a session starts, CCS reconciles the entire active account pool for the provider.
2. Exhaustion Detection: CCS fetches quota status via provider-specific APIs (e.g., Antigravity fetchAvailableModels, Claude policy limits, etc.).
3. Automatic Pausing: If an account is exhausted and a healthy fallback exists, CCS temporarily pauses the exhausted account. This moves the token out of live discovery so the dashboard shows it as paused.
4. Account Selection: CCS selects the 'best' account based on the following priority:
   • Not paused
   • Not exhausted
   • Paid tier preferred over free tier
   • Highest remaining quota

The CCS repository is divided into two primary domains: the CLI source (src/) and the React-based Dashboard UI (ui/src/).

CLI (src/)

Contains the core logic for the Claude Code Switch, including configuration loading, proxy execution, and model pricing resolvers.

Dashboard UI (ui/src/)

A React application organized by domain (e.g., account, analytics, cliproxy, copilot, monitoring, profiles) using barrel exports for easy access. It includes:

• Components: Domain-specific UI elements and shared primitives (via shadcn/ui).
• Contexts: React Contexts for privacy, theme, and websocket management.
• Hooks: Custom domain-prefixed hooks (e.g., useAccounts, useProfiles).
• Pages: Lazy-loaded page components for main views like analytics, settings, api, cliproxy, copilot, and health.

CCS (Claude Code Switch) is a multi-provider profile and runtime manager. It allows users to switch between multiple Claude accounts, alternative AI providers, and different CLI targets (Claude Code, Factory Droid, and Codex CLI) for credential delivery.

The system consists of two primary components:

1. CLI Application: A Node.js TypeScript CLI (src/) used via the terminal.
2. Dashboard UI: A React web application served by Express for management and monitoring.

To build the CCS Bar targets or run the logic tests, you need a Swift 5.9+ toolchain. A full Xcode installation is not required; the macOS CommandLineTools are sufficient.

swift build                 # build all targets, including the app
swift run ccs-bar-check     # run the logic tests (exits non-zero on failure)

To run CCS using Docker, download the docker-compose.yaml file and start the services. This will provide a Dashboard at http://localhost:3000 and a CLIProxy at http://localhost:8317.

Note: The image ghcr.io/kaitranntt/ccs-dashboard:latest is deprecated. Use ghcr.io/kaitranntt/ccs:latest instead.

curl -fsSL https://ccs.kaitran.ca/docker-compose.yaml -o docker-compose.yaml
docker compose up -d

Target adapters can be verified using unit tests for logic (binary detection, environment variable construction) and integration tests via the CLI to ensure the target responds correctly to CCS commands.

# Integration Tests

# Test Claude adapter
ccs --target claude help

# Test Droid adapter (if installed)
ccs --target droid help

# Test Codex adapter (if installed)
ccs --target codex
ccs-codex
ccsxp

# Test argv[0] detection
ccs-droid help
ccsx

If your upstream OpenAI-compatible gateway uses a self-signed or privately issued certificate, you must enable insecure mode in your profile settings JSON:

{
  "env": {
    "CCS_OPENAI_PROXY_INSECURE": "1"
  }
}

This setting is respected by both ccs <profile> auto-routing and ccs proxy start <profile>.