mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-17 14:16:21 +00:00
semantic-release-bot
af6d082f95
## [8.3.0](https://github.com/kaitranntt/ccs/compare/v8.2.0...v8.3.0) (2026-06-14) ### Features * **bar-app:** add CCS icon variants and usage analytics UI ([9b64514](https://github.com/kaitranntt/ccs/commit/9b64514a57f78ff101333caa3daa8c600a48f541)) * **bar-app:** bar-first quota card with sane time formatting ([df96779](https://github.com/kaitranntt/ccs/commit/df967792b91cd6674b39a08b38cb32eaed730ddc)) * **bar-app:** inline spend chart bars/line toggle in the Spend header ([a700a92](https://github.com/kaitranntt/ccs/commit/a700a92171cb16a4d08af7775554c5e501d7228a)) * **bar-app:** label settings clearly and confirm before quit ([26323c1](https://github.com/kaitranntt/ccs/commit/26323c13dfcca42f9ce2dc5e51faa1a65acfc47a)) * **bar-app:** legible tier chips, honest Icon label, dashboard auto-start ([11b3cd5](https://github.com/kaitranntt/ccs/commit/11b3cd5a5cc91b3a8e71a09ea22f43406e2a00a7)) * **bar-app:** per-surface usage UI, unambiguous title, hidden scrollbar ([4a633ea](https://github.com/kaitranntt/ccs/commit/4a633eac65adefab4d04a265d0993172d9fca001)) * **bar-app:** quota gauges, threshold alerts, configurable glance ([559d434](https://github.com/kaitranntt/ccs/commit/559d4340e72e8d900a20e0315f3298ca66e23992)) * **bar-app:** render native subscription accounts with quota gauges ([03077aa](https://github.com/kaitranntt/ccs/commit/03077aa9fdad5b64a22f157c2470bc816da78b4a)) * **bar-app:** retune subscription card palette for the dark theme ([5aa94b5](https://github.com/kaitranntt/ccs/commit/5aa94b5019b3a6efdea4ef5e0b8ac15affd4f966)) * **bar-app:** selectable System/Light/Dark theming ([e33da98](https://github.com/kaitranntt/ccs/commit/e33da989eb7c57f1832864e5d9680d18bce400d5)) * **bar-app:** subscription-first cockpit with detailed quota card ([0e0b912](https://github.com/kaitranntt/ccs/commit/0e0b9121878a18d1e77b8418006468991fa3c981)) * **bar-app:** tune density and add spend chart style toggle ([0b1c4e4](https://github.com/kaitranntt/ccs/commit/0b1c4e490880da83245e87f9de2118438ff42dc4)) * **bar:** add calendar month-to-date spend to analytics ([68f0231](https://github.com/kaitranntt/ccs/commit/68f0231f487a7a56e4571bc67d3171827baebaa5)) * **bar:** add ccs bar --help with docker-style help screen ([9ae6f85](https://github.com/kaitranntt/ccs/commit/9ae6f85fa7d8f204dc9821d1f9c0fde77a44cc1b)) * **bar:** add Get CCS Bar dashboard banner and ccs bar docs page ([1e7ad7e](https://github.com/kaitranntt/ccs/commit/1e7ad7e75e2edd1e36fe9651efd44c464b7f8375)) * **bar:** harden summary against provider hangs and add analytics endpoint ([78f9fc7](https://github.com/kaitranntt/ccs/commit/78f9fc7c0b4c69de48d31147b5501fb50aa99af0)) * **bar:** honest quota state and merged multi-source analytics ([5f850c4](https://github.com/kaitranntt/ccs/commit/5f850c4899a3d7f64385a72a4d1d5080206a1023)) * **bar:** native Claude Code + Codex subscription quota (safe, server-side) ([dbeb0c5](https://github.com/kaitranntt/ccs/commit/dbeb0c543a888d7bc54ed0e3ebfffa63334d1f75)) * **bar:** one-flow install with quarantine automation and launch handoff ([4eef3f7](https://github.com/kaitranntt/ccs/commit/4eef3f77a4a8210501a9dfe369ceeac581772939)), closes [#1504](https://github.com/kaitranntt/ccs/issues/1504) * **bar:** per-window subscription quota detail + codex multi-session scan ([e96967c](https://github.com/kaitranntt/ccs/commit/e96967c22492fe312258bf6ab7f5883250cbc4be)) * **bar:** show running app version in the panel header ([3438c39](https://github.com/kaitranntt/ccs/commit/3438c3940eb0af9a680954526ba63274bf768c30)) * **catalog:** add Claude Fable 5 to Anthropic model registry ([298c89f](https://github.com/kaitranntt/ccs/commit/298c89f2c30712daaf782082903fcb7d93a0ab5e)) * **cli:** add ccs bar command for the macOS menu bar app ([205c2f3](https://github.com/kaitranntt/ccs/commit/205c2f3cd607399031c19e49f37cc64108c13def)) * **cliproxy:** claude pool gap closure - model-neutral launch, shadow warning, provider ban copy ([a257016](https://github.com/kaitranntt/ccs/commit/a257016ebb42ab7f68296188cd71267bab6fecdd)), closes [#1464](https://github.com/kaitranntt/ccs/issues/1464) * **cliproxy:** managed drain order for account pools ([a33e126](https://github.com/kaitranntt/ccs/commit/a33e12619ee3dd7b034a952a51feae9cec69759c)), closes [#1464](https://github.com/kaitranntt/ccs/issues/1464) * **cliproxy:** pool onboarding hints for existing multi-profile users ([0343734](https://github.com/kaitranntt/ccs/commit/0343734665d5610c84297dc50a486d703c6ff28f)), closes [#1464](https://github.com/kaitranntt/ccs/issues/1464) * **cliproxy:** pool routing defaults and safety rails ([fdb0430](https://github.com/kaitranntt/ccs/commit/fdb043083f6a76cc3d33e830d8bd6142827c0cd6)), closes [#1464](https://github.com/kaitranntt/ccs/issues/1464) * **cliproxy:** pool visibility in quota output and dashboard routing card ([74894f6](https://github.com/kaitranntt/ccs/commit/74894f61da26410a214e1b2af2fe8ffd18da5c30)), closes [#1464](https://github.com/kaitranntt/ccs/issues/1464) * **dashboard:** promote CCS Bar globally ([b9356a7](https://github.com/kaitranntt/ccs/commit/b9356a7ce67d783ecbc8b2d0d4ba70e25176b660)) * **macos-bar:** add ad-hoc packaging script + Info.plist ([df4554f](https://github.com/kaitranntt/ccs/commit/df4554fe1f9a0d3d4e43e2b21f454fb862a131c5)) * **macos-bar:** add CCS Bar core (client, models, discovery) + tests ([23abf6a](https://github.com/kaitranntt/ccs/commit/23abf6a6350015dbbc97159564f5ee2678beaf6f)) * **macos-bar:** add SwiftUI MenuBarExtra app + view-model ([e7001fc](https://github.com/kaitranntt/ccs/commit/e7001fc252c4eea1075d89c2455f8fb29164fdf4)) * **quota:** add per-provider tier-lock account selection ([40f32eb](https://github.com/kaitranntt/ccs/commit/40f32ebbf06937b85f7e151169ae93399a1dca04)) * **usage:** attribute CLIProxy usage to accounts for per-account cost ([1867116](https://github.com/kaitranntt/ccs/commit/1867116472dca0d579d34cc82a3aff3268c7648a)) * **web-server:** add /api/bar/summary aggregator with force-fresh ([6d3fde9](https://github.com/kaitranntt/ccs/commit/6d3fde9ed399845a8aa757b4a7c706395e962dc6)) ### Bug Fixes * **bar-app:** periodic background refresh so the glance self-heals ([28fef67](https://github.com/kaitranntt/ccs/commit/28fef67a453fc50cbbca03d2e8b51ce63e2a983f)) * **bar-app:** settings as standalone window, real theme forcing, roomier layout ([b950b41](https://github.com/kaitranntt/ccs/commit/b950b41503352bf019b3070e84a44740750c2be1)) * **bar:** bind 'ccs bar launch' server to IPv4 loopback ([2f8745b](https://github.com/kaitranntt/ccs/commit/2f8745bc1f54f12caa773e716a03e71b6b44bec0)) * **bar:** capture click location synchronously before async panel anchoring ([54a670c](https://github.com/kaitranntt/ccs/commit/54a670c943e8599bd103421e0cdb6212b31f5f67)) * **bar:** correct the already-running reinstall hint ([3aab14c](https://github.com/kaitranntt/ccs/commit/3aab14ca85f704cfda95f3e4d3769fb6f5cca4c7)) * **bar:** harden install handoff per review ([dfc8b7d](https://github.com/kaitranntt/ccs/commit/dfc8b7d1dcca23a3c2f905b6e5e6f7bdd5195752)) * **bar:** keep header version label rightmost during refresh ([a5c4186](https://github.com/kaitranntt/ccs/commit/a5c41864b3710b31b9cd740305928f76643d9a35)) * **bar:** keep menu bar panel on the clicked screen in multi-display setups ([70dc53d](https://github.com/kaitranntt/ccs/commit/70dc53d947e54e23d7befb422fbd1f556f8b57f5)), closes [#1502](https://github.com/kaitranntt/ccs/issues/1502) [#1503](https://github.com/kaitranntt/ccs/issues/1503) * **bar:** probe IPv6 loopback when detecting a running CCS server ([3569297](https://github.com/kaitranntt/ccs/commit/3569297b6d0b7d36d5ec24bb1e0daeadebd42b4e)) * **bar:** read app version from Info.plist and verify bar API instead of version majors ([c572d9f](https://github.com/kaitranntt/ccs/commit/c572d9f8608a14d1150b6c9cf8064fd9e6f77417)), closes [#1497](https://github.com/kaitranntt/ccs/issues/1497) * **bar:** read codex rollout tail via fs so quota surfaces under node ([2e99b58](https://github.com/kaitranntt/ccs/commit/2e99b58d095b847d0f8862b634262ae79a5666d5)) * **bar:** resolve pre-dev review findings (security gate, honesty, correctness) ([7d3a11a](https://github.com/kaitranntt/ccs/commit/7d3a11a45278c4507070c958d8ce33c11b157c0b)) * **bar:** reuse a running CCS web-server and probe ports on the bind host ([af1a2a0](https://github.com/kaitranntt/ccs/commit/af1a2a0f5d74ec368e1edbdd936b1d8024925188)), closes [#1500](https://github.com/kaitranntt/ccs/issues/1500) * **bar:** stage downloads and swap so reinstall never strands the user ([cf3bd8a](https://github.com/kaitranntt/ccs/commit/cf3bd8a5efb4e1166650d5a3d0d4002f59b6f3dc)) * **bar:** stop install at the manual step when quarantine clearing fails ([015cc4d](https://github.com/kaitranntt/ccs/commit/015cc4dd320728f152b13a924b9dceb1c8ea441f)) * **bar:** verify server compat before Gatekeeper steps and harden reinstall ([f68c08e](https://github.com/kaitranntt/ccs/commit/f68c08ede3188e2f58f74c50049bd72d06ad4ee6)) * **cli:** harden ccs bar install + align launch path ([63d10cb](https://github.com/kaitranntt/ccs/commit/63d10cb2d0d20d6512fe623cf7d13c3ddc669e61)) * **cliproxy:** close second-round review gaps in pool onboarding and remote env ([7b8a6f5](https://github.com/kaitranntt/ccs/commit/7b8a6f5cceabddf7a68cc66014ef0ec6eba3e96e)) * **cliproxy:** guard upstream response timeout cleanup against detached socket ([f59536a](https://github.com/kaitranntt/ccs/commit/f59536a81fd0a2ca4dc58a2e3c89b463bb57150c)) * **cliproxy:** harden account pools per pre-merge usefulness review ([1c90388](https://github.com/kaitranntt/ccs/commit/1c90388b5d16a3c8f7895f86bc9a769cb0800de3)) * **cliproxy:** silence legacy-config skip in pool opt-in prompt ([cff9008](https://github.com/kaitranntt/ccs/commit/cff9008f49643bac027de4a3f7eeb010f601ed8b)) * **macos-bar:** correct set-default key, lead account, asset name ([8350c24](https://github.com/kaitranntt/ccs/commit/8350c247333cec3494409543f4030802b8c768d5)) * **mcp:** retry Claude user config locks ([cf90f48](https://github.com/kaitranntt/ccs/commit/cf90f48240db2666186eec08dce329690d26d60e)) * **proxy:** add Anthropic passthrough mode for coding-agent-only endpoints ([b98b0df](https://github.com/kaitranntt/ccs/commit/b98b0df0846944225889167658d9d6251d28baab)) * **proxy:** route Anthropic passthrough by upstream profile ([bb9d23a](https://github.com/kaitranntt/ccs/commit/bb9d23ad6a5597eadc2b3c23a773c60b3c78ad31)) * **quota:** reject tier-lock for non-managed providers ([b9a1084](https://github.com/kaitranntt/ccs/commit/b9a1084bd4c6437e34563f10a4b6ce9b09f14224)) * **test:** restore real account modules in tier-lock to fully stop mock leak ([ad9bdd5](https://github.com/kaitranntt/ccs/commit/ad9bdd5794963b25dce2e3da49b4a0ad18b7fe75)) * **test:** run bucket paths explicitly ([27c8a95](https://github.com/kaitranntt/ccs/commit/27c8a9570ba7a3b8879539a5817e3f76bbf30d42)) * **test:** stop tier-lock mock.module leaking an empty PROVIDERS_WITHOUT_EMAIL ([0770b89](https://github.com/kaitranntt/ccs/commit/0770b8903748c83fd1debe3c7c5d489ae72b1c3a)) * **usage:** compute cost fallback lazily to stop event-loop stall ([f073434](https://github.com/kaitranntt/ccs/commit/f0734348d032d5267e1816cf908f60fd742a97e5)) * **usage:** correct per-account cost attribution ([cc7ac55](https://github.com/kaitranntt/ccs/commit/cc7ac553e326d7db84ef6ed02211a5afb58e4875)) ### Documentation * **bar:** align install docs with Info.plist version pinning and bar-API check ([e7f3ec0](https://github.com/kaitranntt/ccs/commit/e7f3ec0da1142efa1536ad3f4b95ddfdde097e25)) * **bar:** troubleshooting reflects reuse-first launch behavior ([db1d125](https://github.com/kaitranntt/ccs/commit/db1d125f83e2a967230be186ae31b2804c6c8177)) ### Performance Improvements * **bar:** probe reuse candidates concurrently to avoid launch stalls ([2fd90ff](https://github.com/kaitranntt/ccs/commit/2fd90fff9bd59b18a2dac713a24ca05363b12759)) ### Tests * **ci:** allow temporary epic branch in PR trigger assertion ([22d4c72](https://github.com/kaitranntt/ccs/commit/22d4c727172567787a7719a87bdda0c3e960011b)) ### CI * drop temporary epic branch from PR trigger ([2b7cfa3](https://github.com/kaitranntt/ccs/commit/2b7cfa32c8b7bde8cf1ab5f8f272a50fedb10c7e)) * run PR CI for account-pools epic branch ([5101e21](https://github.com/kaitranntt/ccs/commit/5101e21ecd7f7990b06ba6aad05f7d1ba888f24f))
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.
[Docker]
ghcr.io/kaitranntt/ccs-dashboard:latestis deprecated. Useghcr.io/kaitranntt/ccs:latestinstead. See #1251 and docker/README.md for migration details. To wire a sibling container to CLIProxy, see Connect your app to CLIProxy.
Quick Start (Docker)
With Docker installed:
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
Install on Host (npm)
npm install -g @kaitranntt/ccs
ccs config
Then launch whatever runtime fits the task:
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.
ccs api create --preset hf
ccs hf
Need to manage the proxy manually?
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
Related Project: claude-code-router
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 |
| First successful session | /getting-started/first-session |
| Visual walkthrough | /getting-started/product-tour |
| Provider selection | /providers/concepts/overview |
| Full command reference | /reference/cli-commands |
| Troubleshooting | /reference/troubleshooting |
See CCS In Action
CCS Bar For macOS
CCS Bar puts live subscription quota, daily spend, and account controls in the
macOS menu bar. Install it with ccs bar install, launch it with ccs bar, and
tell us what would make it more useful: issues and ideas are welcome in
GitHub Issues.
Deep dive: CCS Bar.
Usage Analytics
Track usage, costs, and session patterns across profiles. Deep dive: 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.
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.
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 | Browser Automation.
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 |
| Install CCS cleanly on a new machine | Installation |
| Go from install to a successful first run | Your First CCS Session |
| See the dashboard and workflow surfaces before setup | Product Tour |
| Install the native macOS menu-bar companion | CCS Bar |
| Compare OAuth providers, Claude accounts, and API profiles | Provider Overview |
| Learn the dashboard structure and feature pages | Dashboard Overview |
| Configure profiles, paths, and environment variables | Configuration |
| Understand browser attach vs Codex browser tooling | Browser Automation |
| Keep OpenCode aligned with your live CCS setup | OpenCode Sync Plugin |
| Browse every command and flag | CLI Commands |
| Recover from install, auth, or provider failures | Troubleshooting |
| Understand storage, config, and architecture details | Reference |
Example Workflow
# 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 | @JasonLandbridge | Auto-sync CCS providers into OpenCode |
Contribute And Report Safely
- Contributing guide: CONTRIBUTING.md
- Daily local gate:
bun run format && bun run lint:fix && bun run validate(validateis 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, help wanted
- Questions: open a question issue
- Security reports: SECURITY.md and the private advisory form