tiennm99/ccs
1
0
Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-07-16 12:15:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update documentation for CCS v7.14.x with quota management

Browse Source
This commit is contained in:
kaitranntt
2026-01-06 18:05:05 -05:00
parent ec2e491c18
commit ec4c2c2f7b
6 changed files with 93 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/code-standards.md
+1 -1
View File
@@ -1,6 +1,6 @@
# CCS Code Standards
Last Updated: 2025-12-21
Last Updated: 2026-01-06
Code standards, modularization patterns, and conventions for the CCS codebase.
docs/codebase-summary.md
+7 -4
View File
@@ -1,8 +1,8 @@
# CCS Codebase Summary
Last Updated: 2025-12-22
Last Updated: 2026-01-06
Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, and v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers.
Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers, and v7.14 Hybrid Quota Management.
## Repository Structure
@@ -71,6 +71,8 @@ src/
│ ├── cliproxy-executor.ts # Main executor (666 lines)
│ ├── config-generator.ts # Config file generation (531 lines)
│ ├── account-manager.ts # Account management (509 lines)
│ ├── quota-manager.ts # Hybrid quota management (NEW v7.14)
│ ├── quota-fetcher.ts # Provider quota API integration (NEW v7.14)
│ ├── platform-detector.ts # OS/arch detection
│ ├── binary-manager.ts # Binary download/update
│ ├── auth-handler.ts # Authentication handling
@@ -79,8 +81,8 @@ src/
│ ├── service-manager.ts # Background service
│ ├── proxy-detector.ts # Running proxy detection
│ ├── startup-lock.ts # Race condition prevention
│ ├── remote-proxy-client.ts # Remote proxy health checks (NEW v7.1)
│ ├── proxy-config-resolver.ts # CLI/env/config merging (NEW v7.1)
│ ├── remote-proxy-client.ts # Remote proxy health checks (v7.1)
│ ├── proxy-config-resolver.ts # CLI/env/config merging (v7.1)
│ ├── types.ts # ResolvedProxyConfig for local/remote modes
│ └── [more files...]
│
@@ -164,6 +166,7 @@ src/
| Auth | `auth/`, `cliproxy/auth/` | Authentication across providers |
| Config | `config/`, `types/` | Configuration & type definitions |
| Providers | `cliproxy/`, `copilot/`, `glmt/` | Provider integrations (7 CLIProxy providers: gemini, codex, agy, qwen, iflow, kiro, ghcp) |
| Quota | `cliproxy/quota-*.ts`, `account-manager.ts` | Hybrid quota management (v7.14) |
| Remote Proxy | `cliproxy/remote-*.ts`, `proxy-config-resolver.ts` | Remote CLIProxy support (v7.1) |
| Services | `web-server/`, `api/` | HTTP server, API services |
| Utilities | `utils/`, `management/` | Helpers, diagnostics |
docs/project-overview-pdr.md
+23 -3
View File
@@ -1,6 +1,6 @@
# CCS Product Development Requirements (PDR)
Last Updated: 2025-12-22
Last Updated: 2026-01-06
## Product Overview
@@ -8,9 +8,9 @@ Last Updated: 2025-12-22
**Tagline**: The universal AI profile manager for Claude Code
**Description**: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, OpenRouter) with a React-based dashboard for configuration management. Supports both local and remote CLIProxyAPI instances.
**Description**: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, OpenRouter, Qwen, Kimi, DeepSeek) with a React-based dashboard for configuration management. Supports both local and remote CLIProxyAPI instances with hybrid quota management.
**Current Version**: v7.2.x (Kiro + GitHub Copilot OAuth providers)
**Current Version**: v7.14.x (Hybrid Quota Management + Pause/Resume)
---
@@ -98,6 +98,14 @@ CCS provides:
- Protocol-based default ports (443 for HTTPS, 8317 for HTTP)
- Dashboard UI for remote server configuration and testing
### FR-009: Quota Management (v7.14)
- Pause/resume individual accounts via `ccs cliproxy pause/resume <account>`
- Check quota status via `ccs cliproxy status [account]`
- Auto-failover when account exhausted
- Tier detection: free/paid/unknown
- Pre-flight quota checks before session start
- Dashboard UI with pause/resume toggles and tier badges
---
## Non-Functional Requirements
@@ -216,6 +224,13 @@ CCS provides:
- [x] Authorization Code flow for Kiro (port 9876)
- [x] Device Code flow for ghcp (no local port needed)
### v7.14 Release (Complete)
- [x] Hybrid quota management with auto-failover
- [x] `ccs cliproxy pause/resume/status` commands
- [x] API tier detection (free/paid/unknown)
- [x] Dashboard pause/resume toggles and tier badges
- [x] Pre-flight quota checks before session start
### v8.0 Release (Planned - Q1 2026)
- [ ] Multiple CLIProxyAPI instances (load balancing, failover)
- [ ] Native git worktree support
@@ -239,6 +254,11 @@ CCS provides:
- AWS Kiro (Authorization Code OAuth)
- Z.AI GLM API
- OpenRouter API
- Moonshot Kimi API
- DeepSeek API
- Alibaba Qwen API
- Minimax API
- Azure Foundry API
### Third-Party Libraries
- Express.js (web server)
docs/project-roadmap.md
+5 -2
View File
@@ -1,6 +1,6 @@
# CCS Project Roadmap
Last Updated: 2025-12-22
Last Updated: 2026-01-06
Forward-looking roadmap documenting current priorities, GitHub issues, and future feature plans.
@@ -23,6 +23,7 @@ All major modularization work is complete. The codebase evolved from monolithic
| 9 | Test Infrastructure | 99 UI tests + 539 CLI tests, 90% coverage |
| 10 | Remote CLIProxy | `proxy-config-resolver.ts`, `remote-proxy-client.ts` |
| 11 | Kiro + ghcp Providers | OAuth support via CLIProxyAPIPlus (v7.2) |
| 12 | Hybrid Quota Management | `quota-manager.ts`, `quota-fetcher.ts` (v7.14) |
**Metrics Achieved**:
- Files >500 lines: 12 -> 5 (-58%)
@@ -153,6 +154,7 @@ worktrees:
- **#158**: Fix AGY OAuth flow
- **#157**: ~~Add Kiro auth support from CLIProxyAPIPlus~~ **COMPLETE** (v7.2)
- GitHub Copilot (ghcp) Device Code flow **COMPLETE** (v7.2)
- Hybrid quota management **COMPLETE** (v7.14)
---
@@ -163,9 +165,10 @@ worktrees:
| Modularization (Phases 1-9) | COMPLETE | - |
| Remote CLIProxy Support (#142) | COMPLETE | v7.1 |
| Kiro + GitHub Copilot OAuth (#157) | COMPLETE | v7.2 |
| Hybrid Quota Management | COMPLETE | v7.14 |
| Critical Bug Fixes (#158, #155, #124) | PLANNED | Q1 2026 |
| Multiple CLIProxyAPI Instances | PLANNED | Q1 2026 |
| Git Worktree Support | PLANNED | Q1 2026 |
| Git Worktree Support | PLANNED | Q2 2026 |
| Enhanced Model Support | PLANNED | Q2 2026 |
---
docs/system-architecture.md
+55 -4
View File
@@ -1,6 +1,6 @@
# CCS System Architecture
Last Updated: 2025-12-22
Last Updated: 2026-01-06
High-level architecture documentation for the CCS (Claude Code Switch) system.
@@ -8,12 +8,12 @@ High-level architecture documentation for the CCS (Claude Code Switch) system.
## System Overview
CCS is a CLI wrapper that enables seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, Kiro, GitHub Copilot). It consists of two main components:
CCS is a CLI wrapper that enables seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, Kiro, GitHub Copilot, OpenRouter, Qwen, Kimi, DeepSeek). It consists of two main components:
1. **CLI Application** (`src/`) - Node.js TypeScript CLI
2. **Dashboard UI** (`ui/`) - React web application served by Express
CCS v7.2 adds Kiro (AWS) and GitHub Copilot (ghcp) OAuth providers via CLIProxyAPIPlus.
CCS v7.14 adds Hybrid Quota Management with pause/resume/status commands and auto-failover.
```
+===========================================================================+
@@ -131,7 +131,9 @@ CCS v7.2 adds Kiro (AWS) and GitHub Copilot (ghcp) OAuth providers via CLIProxyA
| cliproxy-executor| | copilot-package- | | glmt-proxy |
| config-generator | | manager | | delta-accumulator|
| account-manager | | [copilot logic] | | pipeline/ |
| auth/ | +------------------+ +------------------+
| quota-manager | +------------------+ +------------------+
| quota-fetcher |
| auth/ |
| binary/ |
| services/ |
+------------------+
@@ -424,6 +426,55 @@ CCS v7.2 adds Kiro (AWS) and GitHub Copilot (ghcp) OAuth providers via CLIProxyA
CCS_PROXY_FALLBACK_ENABLED Enable fallback (true/false)
```
### Quota Management Flow (v7.14)
```
+===========================================================================+
| Quota Management Architecture |
+===========================================================================+
Pre-Flight Check (before session start)
|
v
+------------------+
| quota-manager.ts | Hybrid quota management
+------------------+
|
+---> Get all active accounts for provider
|
+---> For each account:
| |
| v
| +------------------+
| | quota-fetcher.ts | Provider-specific API calls
| +------------------+
| |
| +---> Check isPaused flag --> Skip if paused
| |
| +---> Fetch quota from provider API
| | - Gemini: /models endpoint
| | - Codex: /api/v1/account
| | - Kiro: /api/usage
| |
| +---> Detect tier (free/paid/unknown)
| |
| +---> Check exhaustion status
|
+---> Select best account (not paused, not exhausted)
|
+---> Auto-failover to next account if current exhausted
CLI Commands:
ccs cliproxy pause <account> --> Set isPaused=true in account-manager
ccs cliproxy resume <account> --> Set isPaused=false
ccs cliproxy status [account] --> Display quota + tier info
Dashboard UI:
- Pause/Resume toggle per account
- Tier badge (free/paid/unknown)
- Quota usage display
```
---
## Configuration Architecture
docs/websearch.md
+2
View File
@@ -1,5 +1,7 @@
# WebSearch Configuration Guide
Last Updated: 2026-01-06
CCS provides automatic web search capability for all profiles, including third-party providers that cannot access Anthropic's native WebSearch API.
## How WebSearch Works