mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-16 04:18:05 +00:00
Kai (Tam Nhu) TranandGitHub
107b5b5db4
* docs(quickstart): fix raw URL for corporate-proxy fallback (H1) * feat(docker)!: drop :full image variant — use sibling containers on ccs-net (Q3) No AI CLIs (claude-code/gemini-cli/grok-cli/opencode) are bundled in the image. Use sibling containers attached to ccs-net instead. See docker/README.md#connect-your-app-to-cliproxy. Also removes bash from apk deps (entrypoint uses #!/bin/sh — L2). ci(docker): publish only immutable :<ver> tag pre-smoke; promote-mutable-tags job adds :latest/:MAJOR/:MINOR aliases only after smoke tests pass (H3) ci(docker): smoke-test-compose-url runs network-contract.sh against the downloaded /tmp/ccs-compose.yaml instead of re-cloning the repo (H4) ci(docker): sign published images with cosign keyless OIDC + attach provenance/SBOM via build-push-action (M8) test(docker): network-contract.sh now accepts compose-file and image-ref positional args; replaces python3 healthcheck parser with jq (L4) * chore(release): cut every main release as rc.N prerelease, manual promote flow (H2) - .releaserc.cjs: main branch now uses prerelease 'rc' channel — every semantic-release cut becomes vX.Y.Z-rc.N - add promote-release.yml: workflow_dispatch flips rc → stable via 'gh release edit --prerelease=false'; triggers docker promote-mutable-tags - add docs/release-process.md: full soak + promote procedure, rollback steps, cosign verification command - releaseNotesGenerator: add revert section, document chore hidden behaviour (L8) * fix(docker): healthcheck probes both dashboard and cliproxy ports (M1) compose.yaml healthcheck now checks :3000 and :8317 concurrently with a 4.5s internal timeout, within Docker's 5s timeout budget. Also: - docs(docker): document npm lockfile ephemeral tradeoff above install layer; note size-budget regression test as the practical safeguard (M3) - docs(docker): drop :full row from Choosing an image table; add sibling container note pointing to connect-your-app-to-cliproxy (Q3/docs) - docs(docker): remove :full docker run block; fix release-tag sentence (Q3) - docs(docker): fix raw URL in migration section (H1 parity) - docs(docker): add Volume warning — 'down -v' deletes named volumes (L13) - docs(docker): update What changes table — remove :full reference (Q3) - docs(docker): add Image Signatures and SBOM section with cosign verify and sbom download commands (M8/docs) - changelog: add Unreleased entries for rc soak, cosign signing, :full removal with migration guidance * ci(docker): assert image-size budget per platform; add compose parity + breaking-change guard (M6/L9/L12) - image-size.sh: add --platform flag; uses 'docker buildx imagetools inspect' to sum compressed layer sizes from registry manifest for linux/amd64 and linux/arm64 separately (M6) - docker-release.yml smoke-test: runs size check for both platforms - compose-parity.sh: diffs docker/compose.yaml vs docker/docker-compose.integrated.yml for image name, ports 3000/8317, volume mounts /root/.ccs and /var/log/ccs, ccs-net definition (L12) - ci.yml: add compose-parity job wired to cliproxy runner (L12) - breaking-change-guard.yml: fails PR if compose.yaml changes image name, network name, or container_name without a feat!/fix! commit (L9) * chore(ci): fix cosign shell substitution — use tr instead of bash @L expansion (L6/nit) * test(docker): fix compose-parity port regex for variable-interpolated host ports
214 lines
9.1 KiB
Markdown
214 lines
9.1 KiB
Markdown
<div align="center">
|
|
|
|
# CCS - Claude Code Switch
|
|
|
|
|
|
|
|
### The multi-provider profile and runtime manager for Claude Code and compatible CLIs
|
|
|
|
Run Claude, Codex, Droid-routed profiles, GLM, local models, and
|
|
Anthropic-compatible APIs without config thrash.
|
|
|
|
[](LICENSE)
|
|
[](https://www.npmjs.com/package/@kaitranntt/ccs)
|
|
[](https://claudekit.cc?ref=HMNKXOHN)
|
|
|
|
**[Website](https://ccs.kaitran.ca)** |
|
|
**[Documentation](https://docs.ccs.kaitran.ca)** |
|
|
**[Product Tour](https://docs.ccs.kaitran.ca/getting-started/product-tour)** |
|
|
**[CLI Reference](https://docs.ccs.kaitran.ca/reference/cli-commands)**
|
|
|
|
</div>
|
|
|
|
> **[Docker]** `ghcr.io/kaitranntt/ccs-dashboard:latest` is deprecated. Use `ghcr.io/kaitranntt/ccs:latest` instead. See [#1251](https://github.com/kaitranntt/ccs/issues/1251) and [docker/README.md](docker/README.md#choosing-an-image) for migration details. To wire a sibling container to CLIProxy, see [Connect your app to CLIProxy](docker/README.md#connect-your-app-to-cliproxy).
|
|
|
|
<!-- quickstart-snippet-start -->
|
|
## Quick Start (Docker)
|
|
|
|
With Docker installed:
|
|
|
|
```bash
|
|
curl -fsSL https://ccs.kaitran.ca/docker-compose.yaml -o docker-compose.yaml
|
|
docker compose up -d
|
|
```
|
|
|
|
Dashboard at http://localhost:3000 · CLIProxy at http://localhost:8317.
|
|
|
|
Need a corporate-proxy alternative? Download directly:
|
|
`https://raw.githubusercontent.com/kaitranntt/ccs/main/docker/compose.yaml`
|
|
<!-- quickstart-snippet-end -->
|
|
|
|
## Install on Host (npm)
|
|
|
|
```bash
|
|
npm install -g @kaitranntt/ccs
|
|
ccs config
|
|
```
|
|
|
|
Then launch whatever runtime fits the task:
|
|
|
|
```bash
|
|
ccs
|
|
ccs codex
|
|
ccs --target droid glm
|
|
ccs glm
|
|
ccs ollama
|
|
```
|
|
|
|
## Why CCS
|
|
|
|
CCS gives you one stable command surface while letting you switch between:
|
|
|
|
- multiple runtimes such as Claude Code, Factory Droid, and Codex CLI
|
|
- multiple Claude subscriptions and isolated account contexts
|
|
- OAuth providers like Codex, Kiro, Claude, Qwen, Kimi, and more, with legacy
|
|
Copilot compatibility for existing setups
|
|
- API and local-model profiles like GLM, Kimi, OpenRouter, Ollama, llama.cpp,
|
|
Novita, and Alibaba Coding Plan
|
|
|
|
The goal is simple: stop rewriting config files, stop breaking active sessions,
|
|
and move between providers in seconds.
|
|
|
|
## OpenAI-Compatible Routing
|
|
|
|
CCS can now bridge Claude Code into OpenAI-compatible providers through a local
|
|
Anthropic-compatible proxy instead of requiring a native Anthropic upstream.
|
|
|
|
```bash
|
|
ccs api create --preset hf
|
|
ccs hf
|
|
```
|
|
|
|
Need to manage the proxy manually?
|
|
|
|
```bash
|
|
ccs proxy start hf
|
|
eval "$(ccs proxy activate)"
|
|
```
|
|
|
|
The proxy also supports request-time `profile:model` selectors, scenario-based
|
|
model routing through `proxy.routing`, and explicit activation helpers such as
|
|
`ccs proxy activate --fish`.
|
|
|
|
Guide: [OpenAI-Compatible Provider Routing](./docs/openai-compatible-providers.md)
|
|
|
|
### Related Project: claude-code-router
|
|
|
|
[claude-code-router](https://github.com/musistudio/claude-code-router) is an
|
|
excellent standalone tool for routing Claude Code requests to OpenAI-compatible
|
|
providers. CCS's local proxy and SSE transformation work was directly informed
|
|
by CCR's transformer architecture.
|
|
|
|
Use CCR when you want a standalone router without CCS profile management.
|
|
Use CCS when you want the routing flow integrated with CCS profiles, runtime
|
|
bridges, and the existing `ccs` command surface.
|
|
|
|
Need the full setup path instead of the short version?
|
|
|
|
| Need | Start here |
|
|
| --- | --- |
|
|
| Install and verify CCS | [`/getting-started/installation`](https://docs.ccs.kaitran.ca/getting-started/installation) |
|
|
| First successful session | [`/getting-started/first-session`](https://docs.ccs.kaitran.ca/getting-started/first-session) |
|
|
| Visual walkthrough | [`/getting-started/product-tour`](https://docs.ccs.kaitran.ca/getting-started/product-tour) |
|
|
| Provider selection | [`/providers/concepts/overview`](https://docs.ccs.kaitran.ca/providers/concepts/overview) |
|
|
| Full command reference | [`/reference/cli-commands`](https://docs.ccs.kaitran.ca/reference/cli-commands) |
|
|
| Troubleshooting | [`/reference/troubleshooting`](https://docs.ccs.kaitran.ca/reference/troubleshooting) |
|
|
|
|
## See CCS In Action
|
|
|
|
### Usage Analytics
|
|
|
|
|
|
|
|
Track usage, costs, and session patterns across profiles. Deep dive:
|
|
[Dashboard Analytics](https://docs.ccs.kaitran.ca/features/dashboard/analytics).
|
|
|
|
### Live Auth And Health Monitoring
|
|
|
|
|
|
|
|
See auth state, account health, and provider readiness without dropping into raw
|
|
config. Deep dive:
|
|
[Live Auth Monitor](https://docs.ccs.kaitran.ca/features/dashboard/live-auth-monitor).
|
|
|
|
### OAuth Provider Control Center
|
|
|
|
|
|
|
|
Manage OAuth-backed providers, quota visibility, and proxy-wide routing from one place. CCS now
|
|
surfaces round-robin vs fill-first natively in both CLI and dashboard flows instead of hiding that
|
|
choice inside raw upstream controls. The original CLIProxyAPI backend remains the default; the
|
|
community-maintained CLIProxyAPIPlus fork is opt-in for plus-only providers. When Plus is selected,
|
|
CCS points the embedded management panel at the maintained CPAMC dashboard fork by default.
|
|
Deep dive:
|
|
[CLIProxy API](https://docs.ccs.kaitran.ca/features/proxy/cliproxy-api).
|
|
|
|
### Managed Tooling And Fallbacks
|
|
|
|
|
|
|
|
CCS can provision first-class local tools like WebSearch and image analysis for
|
|
third-party launches instead of leaving you to wire them by hand. Browser
|
|
automation now has a first-class setup path as well. Deep dive:
|
|
[WebSearch](https://docs.ccs.kaitran.ca/features/ai/websearch) |
|
|
[Browser Automation](./docs/browser-automation.md).
|
|
|
|
## Docs Matrix
|
|
|
|
The README stays short on purpose. The docs site owns the detailed guides and
|
|
reference material.
|
|
|
|
| If you want to... | Read this |
|
|
| --- | --- |
|
|
| Understand what CCS is and how the pieces fit together | [Introduction](https://docs.ccs.kaitran.ca/introduction) |
|
|
| Install CCS cleanly on a new machine | [Installation](https://docs.ccs.kaitran.ca/getting-started/installation) |
|
|
| Go from install to a successful first run | [Your First CCS Session](https://docs.ccs.kaitran.ca/getting-started/first-session) |
|
|
| See the dashboard and workflow surfaces before setup | [Product Tour](https://docs.ccs.kaitran.ca/getting-started/product-tour) |
|
|
| Compare OAuth providers, Claude accounts, and API profiles | [Provider Overview](https://docs.ccs.kaitran.ca/providers/concepts/overview) |
|
|
| Learn the dashboard structure and feature pages | [Dashboard Overview](https://docs.ccs.kaitran.ca/features/dashboard/overview) |
|
|
| Configure profiles, paths, and environment variables | [Configuration](https://docs.ccs.kaitran.ca/getting-started/configuration) |
|
|
| Understand browser attach vs Codex browser tooling | [Browser Automation](./docs/browser-automation.md) |
|
|
| Keep OpenCode aligned with your live CCS setup | [OpenCode Sync Plugin](https://docs.ccs.kaitran.ca/features/workflow/opencode-sync) |
|
|
| Browse every command and flag | [CLI Commands](https://docs.ccs.kaitran.ca/reference/cli-commands) |
|
|
| Recover from install, auth, or provider failures | [Troubleshooting](https://docs.ccs.kaitran.ca/reference/troubleshooting) |
|
|
| Understand storage, config, and architecture details | [Reference](https://docs.ccs.kaitran.ca/reference/architecture) |
|
|
|
|
## Example Workflow
|
|
|
|
```bash
|
|
# Design with default Claude
|
|
ccs "design the auth flow"
|
|
|
|
# Implement with a different provider
|
|
ccs codex "implement the user service"
|
|
|
|
# Use a cheaper API profile for routine work
|
|
ccs glm "clean up tests and docs"
|
|
|
|
# Run a local model when you need privacy or offline access
|
|
ccs ollama "summarize these logs"
|
|
```
|
|
|
|
## Community Projects
|
|
|
|
| Project | Author | Description |
|
|
| --- | --- | --- |
|
|
| [opencode-ccs-sync](https://github.com/JasonLandbridge/opencode-ccs-sync) | [@JasonLandbridge](https://github.com/JasonLandbridge) | Auto-sync CCS providers into OpenCode |
|
|
|
|
## Contribute And Report Safely
|
|
|
|
- Contributing guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
|
|
- Daily local gate: `bun run format && bun run lint:fix && bun run validate` (`validate` is the fast path only)
|
|
- Before review or merge confidence: `bun run validate:ci-parity`
|
|
- If PR checks stay queued for more than 10 minutes, assume the self-hosted runner is offline and notify a maintainer instead of retrying blindly
|
|
- Starter work:
|
|
[good first issue](https://github.com/kaitranntt/ccs/labels/good%20first%20issue),
|
|
[help wanted](https://github.com/kaitranntt/ccs/labels/help%20wanted)
|
|
- Questions: [open a question issue](https://github.com/kaitranntt/ccs/issues/new/choose)
|
|
- Security reports: [SECURITY.md](./SECURITY.md) and the
|
|
[private advisory form](https://github.com/kaitranntt/ccs/security/advisories/new)
|
|
|
|
## Star History
|
|
|
|
[](https://www.star-history.com/#kaitranntt/ccs&type=date&legend=top-left)
|