CCS: Manage Claude, Codex, and AI Provider Profiles

CCS, from kaitranntt/ccs, gives several AI coding runtimes one command surface. It can launch Claude Code, Codex CLI, Factory Droid, API-backed profiles such as GLM and Kimi, and local engines such as Ollama. It also separates account contexts, which is useful when work, personal, and team subscriptions must not share authentication state.

The name is easy to confuse with other switchers. This project calls itself Claude Codex Switch. It is not the CC Switch desktop app, and it is not a small script that merely swaps one JSON file.

What CCS manages#

CCS sits between the shell command you type and the runtime or provider you want to launch. Its current documentation groups the choices into runtimes, OAuth-backed providers, API profiles, and local models.

The practical benefit is isolation. Two terminal windows can launch different profiles without repeatedly overwriting the same live configuration. That is safer than copying credential files by hand, although CCS still handles credentials and deserves the same care as a password-bearing developer tool.

flowchart LR
A[ccs command] --> B[Runtime and profile selection]
B --> C[Claude Code]
B --> D[Codex CLI]
B --> E[Other runtime]
B --> F[CLIProxy or API profile]
F --> G[OAuth provider]
F --> H[API provider]
F --> I[Local model]

Install CCS on the host#

The official host installation uses the published npm package:

npm install -g @kaitranntt/ccs
ccs config

Run ccs for the default Claude path or select another runtime or profile:

ccs
ccs codex
ccs glm
ccs ollama
ccs --target droid glm

ccs config is the right place to begin because supported providers and setup flows change faster than a copied configuration example. Confirm the command list in the official CLI reference.

Run CCS with Docker#

Docker keeps the dashboard and proxy services together. The current quick start downloads the project’s Compose file, then starts it:

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

The documented defaults are http://localhost:3000 for the dashboard and http://localhost:8317 for CLIProxy. Inspect the downloaded Compose file before running it. A remote script or Compose file is executable configuration, even when it comes from the project’s own domain.

Accounts, API profiles, and OAuth#

A normal single-account Claude installation does not require a separate account profile. The existing login can run through ccs. Create isolated profiles when you genuinely need different account contexts.

OAuth providers use browser authorization and refreshable tokens. API profiles use provider keys and explicit endpoints. Local profiles point at software such as Ollama or llama.cpp. None of these options is universally safer: browser OAuth reduces copied static keys, while API keys are easier to use on a headless host. Protect both.

The project currently documents OAuth-backed routes for services including Codex and xAI/Grok, plus API or local profiles for GLM, Kimi, OpenRouter, Ollama, llama.cpp, Novita, Fireworks AI, and Alibaba Coding Plan. Treat that list as a snapshot. Run the current configuration command before assuming a provider still uses the same authentication flow.

A sensible daily workflow#

Keep profile names tied to purpose rather than model hype. Names such as work-claude, personal-codex, and local-ollama are easier to audit six months later than fast or best.

1. Launch the default work profile in one terminal.
2. Use a second terminal for a local or lower-cost provider.
3. Keep repositories and account contexts separate.
4. Check the dashboard when usage or authentication behaves unexpectedly.
5. Update CCS before troubleshooting a provider that recently changed its login or model IDs.

CCS also exposes routing strategy controls such as round-robin and fill-first for supported proxy flows. Round-robin spreads work; fill-first consumes one account before moving on. Use only accounts you are authorized to operate, and do not treat account rotation as permission to bypass a provider’s limits or terms.

Security and operational limits#

The dashboard and local proxy are administration surfaces. Bind them to localhost unless you have added authentication, TLS, and network controls for remote access. Back up profile metadata carefully, but avoid putting raw credential directories in ordinary cloud-sync folders or source control.

Third-party launches can also lose features during protocol conversion. Text and tool calls may work while image input, reasoning metadata, or provider-specific caching behaves differently. Test the exact workflow you plan to use.

When CCS is unnecessary#

CCS adds the most value when profiles or runtimes overlap. A developer with one Claude account and no alternate provider can keep using the ordinary claude command. A team that already operates a centrally managed LiteLLM or Requesty gateway may also prefer to keep routing there rather than introduce a second control layer on every workstation.

It is also a poor substitute for organization-wide identity management. Local profile isolation helps prevent accidental crossover on one machine, but it does not provide employee lifecycle controls, central audit policy, or provider-side role assignment. Use the provider’s team administration for those jobs.

Choose CCS when the command-line workflow and local profile separation solve a real daily problem. Fewer moving parts are easier to secure when they do not.

Troubleshooting CCS#

If ccs is not found, check the global npm binary directory and reopen the shell. If the wrong account appears, inspect the selected profile instead of deleting live authentication files. A provider login loop often means its OAuth token needs to be refreshed through the current CCS flow.

For Docker, confirm both containers are healthy and that ports 3000 and 8317 are not already occupied. If an older guide references the deprecated dashboard image, update the Compose configuration first.

When a routed model answers but tool calls fail, compare the runtime, model, and proxy protocol. Try a small task on the provider’s direct supported client to separate an upstream problem from a CCS translation problem.

CCS makes sense when one developer needs several runtimes or isolated provider contexts from the terminal. For a visual provider manager, compare CC Switch. For a gateway built around fallback chains, see 9Router.