diff --git a/README.md b/README.md
index 17ad794c..c1902b03 100644
--- a/README.md
+++ b/README.md
@@ -255,6 +255,37 @@ See [docs/websearch.md](./docs/websearch.md) for detailed configuration and trou
+## Remote CLIProxy
+
+CCS v7.x supports connecting to remote CLIProxyAPI instances, enabling:
+- **Team sharing**: One CLIProxyAPI server for multiple developers
+- **Cost optimization**: Centralized API key management
+- **Network isolation**: Keep API credentials on a secure server
+
+### Quick Setup
+
+Configure via dashboard (**Settings > CLIProxy Server**) or CLI flags:
+
+```bash
+ccs gemini --proxy-host 192.168.1.100 --proxy-port 8317
+ccs codex --proxy-host proxy.example.com --proxy-protocol https
+```
+
+### CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `--proxy-host` | Remote proxy hostname or IP |
+| `--proxy-port` | Remote proxy port (default: 8317 for HTTP, 443 for HTTPS) |
+| `--proxy-protocol` | `http` or `https` (default: http) |
+| `--proxy-auth-token` | Bearer token for authentication |
+| `--local-proxy` | Force local mode, ignore remote config |
+| `--remote-only` | Fail if remote unreachable (no fallback) |
+
+See [Remote Proxy documentation](https://docs.ccs.kaitran.ca/features/remote-proxy) for detailed setup.
+
+
+
## Documentation
| Topic | Link |
diff --git a/docs/code-standards.md b/docs/code-standards.md
index 66a0bb51..b4389cbc 100644
--- a/docs/code-standards.md
+++ b/docs/code-standards.md
@@ -580,6 +580,26 @@ interface Config { ... }
export interface Config { ... }
```
+### 5. Config Priority Pattern
+
+When resolving configuration from multiple sources, follow this priority order:
+
+```typescript
+// proxy-config-resolver.ts pattern
+// Priority: CLI flags > Environment variables > config.yaml > defaults
+
+const resolved = {
+ ...DEFAULT_CONFIG, // 4. Defaults (lowest)
+ ...yamlConfig, // 3. config.yaml
+ ...envConfig, // 2. Environment variables
+ ...cliFlags, // 1. CLI flags (highest)
+};
+```
+
+This pattern is used in:
+- `src/cliproxy/proxy-config-resolver.ts` - Remote proxy config
+- `src/config/unified-config-loader.ts` - Main config loading
+
---
## Related Documentation
diff --git a/docs/codebase-summary.md b/docs/codebase-summary.md
index f71092d1..1f07e61d 100644
--- a/docs/codebase-summary.md
+++ b/docs/codebase-summary.md
@@ -2,7 +2,7 @@
Last Updated: 2025-12-21
-Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure).
+Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure) and v7.1 Remote CLIProxy feature.
## Repository Structure
@@ -79,6 +79,9 @@ 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)
+│ ├── types.ts # ResolvedProxyConfig for local/remote modes
│ └── [more files...]
│
├── copilot/ # GitHub Copilot integration
@@ -161,6 +164,7 @@ src/
| Auth | `auth/`, `cliproxy/auth/` | Authentication across providers |
| Config | `config/`, `types/` | Configuration & type definitions |
| Providers | `cliproxy/`, `copilot/`, `glmt/` | Provider integrations |
+| 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 |
@@ -462,12 +466,14 @@ tests/
| Metric | Value |
|--------|-------|
-| Total Tests | 497 |
-| Passing | 497 |
-| Skipped | 2 |
-| Failed | 0 |
+| CLI Tests | 539 |
+| UI Tests | 99 |
+| Total Tests | 638 |
+| Passing | 612 |
+| Skipped | 6 |
+| Failed | 0 (CLI), 26 (UI - jsdom setup) |
| Coverage Threshold | 90% |
-| Test Files | 29 |
+| Test Files | 38 |
---
diff --git a/docs/project-overview-pdr.md b/docs/project-overview-pdr.md
index b022cf3c..86e36719 100644
--- a/docs/project-overview-pdr.md
+++ b/docs/project-overview-pdr.md
@@ -8,9 +8,9 @@ Last Updated: 2025-12-21
**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.
+**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.
-**Current Version**: v7.x (OpenRouter integration added)
+**Current Version**: v7.1.x (Remote CLIProxy routing, OpenRouter integration)
---
@@ -90,6 +90,14 @@ CCS provides:
- Support Gemini CLI, OpenCode, Grok providers
- Graceful fallback chain
+### FR-008: Remote CLIProxy Support
+- Connect to remote CLIProxyAPI instances
+- CLI flags for proxy configuration (--proxy-host, --proxy-port, etc.)
+- Environment variable configuration (CCS_PROXY_HOST, etc.)
+- Fallback to local proxy when remote unreachable
+- Protocol-based default ports (443 for HTTPS, 8317 for HTTP)
+- Dashboard UI for remote server configuration and testing
+
---
## Non-Functional Requirements
@@ -167,7 +175,7 @@ CCS provides:
| Startup time | < 100ms | Achieved |
| Dashboard load | < 2s | Achieved |
| Error rate | < 1% | Achieved |
-| Test coverage | > 90% | 90% (497 tests) |
+| Test coverage | > 90% | 90% (539 CLI + 99 UI tests) |
| File size compliance | 100% < 200 lines | 95% |
---
@@ -191,7 +199,16 @@ CCS provides:
- [x] Settings page modularization (20 files)
- [x] Analytics page modularization (8 files)
- [x] Auth monitor modularization (8 files)
-- [x] Comprehensive test infrastructure (497 tests)
+- [x] Comprehensive test infrastructure (539 CLI + 99 UI tests)
+
+### v7.1 Release (Complete)
+- [x] Remote CLIProxy routing support
+- [x] CLI flags for remote proxy (--proxy-host, --proxy-port, etc.)
+- [x] Environment variables for proxy config (CCS_PROXY_*)
+- [x] Dashboard remote proxy configuration UI
+- [x] Connection testing with latency display
+- [x] Fallback to local when remote unreachable
+- [x] Protocol-based default ports (HTTPS:443, HTTP:8317)
### v8.0 Release (Planned - Q1 2026)
- [ ] Multiple CLIProxyAPI instances (load balancing, failover)
diff --git a/docs/project-roadmap.md b/docs/project-roadmap.md
index eee5d08f..72f095eb 100644
--- a/docs/project-roadmap.md
+++ b/docs/project-roadmap.md
@@ -17,16 +17,18 @@ All major modularization work is complete. The codebase evolved from monolithic
| 3 | CLIProxy | `src/cliproxy/` with auth/, binary/, services/ subdirs |
| 4 | Utils/Errors | `src/utils/ui/`, `src/errors/`, `src/management/` |
| 5 | UI Components | 5 monster files split into modular dirs (54+ modules) |
-| 6 | Settings Page | `pages/settings/` (1,781→20 files) |
-| 7 | Analytics Page | `pages/analytics/` (420→8 files) |
-| 8 | Auth Monitor | `monitoring/auth-monitor/` (465→8 files) |
-| 9 | Test Infrastructure | 99 UI tests + 497 CLI tests, 90% coverage |
+| 6 | Settings Page | `pages/settings/` (1,781->20 files) |
+| 7 | Analytics Page | `pages/analytics/` (420->8 files) |
+| 8 | Auth Monitor | `monitoring/auth-monitor/` (465->8 files) |
+| 9 | Test Infrastructure | 99 UI tests + 539 CLI tests, 90% coverage |
+| 10 | Remote CLIProxy | `proxy-config-resolver.ts`, `remote-proxy-client.ts` |
**Metrics Achieved**:
-- Files >500 lines: 12 → 5 (-58%)
-- UI files >200 lines: 28 → 8 (-71%)
-- Barrel exports: 5 → 39 (+680%)
-- Test coverage: 0% → 90%
+- Files >500 lines: 12 -> 5 (-58%)
+- UI files >200 lines: 28 -> 8 (-71%)
+- Barrel exports: 5 -> 39 (+680%)
+- Test coverage: 0% -> 90%
+- Total tests: 638 (539 CLI + 99 UI)
---
@@ -59,7 +61,7 @@ All major modularization work is complete. The codebase evolved from monolithic
| Issue | Title | Type | Status |
|-------|-------|------|--------|
-| #142 | Configure with available CLIProxyAPI | enhancement | **IN PROGRESS** |
+| #142 | Configure with available CLIProxyAPI | enhancement | **COMPLETE** (v7.1) |
| #157 | Support for Kiro auth from CLIProxyAPIPlus | enhancement | - |
| #123 | Add More Models | enhancement | Ongoing |
| #114 | OpenCode Zen Free model + Auto Rotation API Key | enhancement | - |
@@ -157,6 +159,7 @@ worktrees:
| Milestone | Status | Target |
|-----------|--------|--------|
| Modularization (Phases 1-9) | COMPLETE | - |
+| Remote CLIProxy Support (#142) | COMPLETE | v7.1 |
| Critical Bug Fixes (#158, #155, #124) | PLANNED | Q1 2026 |
| Multiple CLIProxyAPI Instances | PLANNED | Q1 2026 |
| Git Worktree Support | PLANNED | Q1 2026 |
diff --git a/docs/system-architecture.md b/docs/system-architecture.md
index 632efb6d..91589e57 100644
--- a/docs/system-architecture.md
+++ b/docs/system-architecture.md
@@ -13,6 +13,8 @@ CCS is a CLI wrapper that enables seamless switching between multiple Claude acc
1. **CLI Application** (`src/`) - Node.js TypeScript CLI
2. **Dashboard UI** (`ui/`) - React web application served by Express
+CCS v7.1 adds support for both **local** and **remote** CLIProxyAPI instances.
+
```
+===========================================================================+
| CCS System |
@@ -30,10 +32,10 @@ CCS is a CLI wrapper that enables seamless switching between multiple Claude acc
| +------------------+ +-----------------+ | Gemini/etc) | |
| | +----------------+ |
| v |
-| +-----------------+ |
-| | CLIProxyAPI | |
-| | (Binary) | |
-| +-----------------+ |
+| +---------------------+ |
+| | CLIProxyAPI | |
+| | (Local or Remote) | |
+| +---------------------+ |
| |
+===========================================================================+
```
@@ -350,6 +352,65 @@ CCS is a CLI wrapper that enables seamless switching between multiple Claude acc
+------------------+
```
+### Remote CLIProxy Flow (v7.1)
+
+```
++===========================================================================+
+| Remote CLIProxy Architecture |
++===========================================================================+
+
+ Config Resolution (proxy-config-resolver.ts)
+ |
+ +---> Priority: CLI flags > ENV vars > config.yaml > defaults
+ |
+ v
+ +------------------+
+ | ResolvedProxyConfig |
+ | mode: local|remote |
+ +------------------+
+ |
+ +---> [mode = local] ---> Spawn local CLIProxyAPI binary
+ | |
+ | v
+ | localhost:8317
+ |
+ +---> [mode = remote] ---> Connect to remote server
+ |
+ v
+ +------------------+
+ | Health Check | remote-proxy-client.ts
+ | /v1/models | 2s timeout
+ +------------------+
+ |
+ +---> [reachable] ---> Use remote
+ | |
+ | v
+ | protocol://host:port
+ |
+ +---> [unreachable] ---> Fallback decision
+ |
+ +-----------------------------+
+ |
+ +---> [fallbackEnabled] ---> Start local
+ |
+ +---> [remoteOnly] ---> Fail with error
+
+ CLI Flags:
+ --proxy-host Remote hostname/IP
+ --proxy-port Port (default: 8317 HTTP, 443 HTTPS)
+ --proxy-protocol http or https
+ --proxy-auth-token Bearer authentication
+ --local-proxy Force local mode
+ --remote-only Fail if remote unreachable
+
+ Environment Variables:
+ CCS_PROXY_HOST Remote hostname
+ CCS_PROXY_PORT Remote port
+ CCS_PROXY_PROTOCOL Protocol (http/https)
+ CCS_PROXY_AUTH_TOKEN Auth token
+ CCS_PROXY_FALLBACK_ENABLED Enable fallback (true/false)
+```
+
---
## Configuration Architecture