Quota & Cost Analytics
Relevant source files
The following files were used as context for generating this wiki page:
The Quota & Cost Analytics system in CCS is a multi-provider framework designed to monitor, aggregate, and manage rate limits and usage across various AI providers, including Claude, Codex (ChatGPT), Gemini, and GitHub Copilot. It ensures high availability for CLI and web sessions by providing real-time visibility into remaining quotas, calculating reset horizons, and implementing automatic account failover when thresholds are met.
This module centralizes provider-specific rate-limiting logic into a unified interface, allowing the application to implement hybrid auto-manual account selection. It handles complex data structures such as rotating usage windows (e.g., 5-hour vs. weekly limits) and provides structured error reporting for account health diagnostics.
Sources: src/cliproxy/quota/quota-manager.ts:1-15, ui/src/lib/api-client.ts:543-570
Architecture and Data Flow
The system operates through a layered architecture involving fetchers, managers, and collectors. The QuotaManager serves as the central hub, utilizing a 30-second in-memory cache and request deduplication to prevent redundant API calls to upstream providers.
High-Level Quota Processing Flow
The following diagram illustrates how a quota request is processed from the UI or CLI through the manager to the upstream provider.
The system implements a 30,000ms TTL for cached quota entries to ensure data freshness while reducing latency.
Sources: src/cliproxy/quota/quota-manager.ts:39-106, ui/src/lib/utils.ts:384-400
Provider Specific Quota Structures
The system supports multiple providers, each with distinct quota models. These are transformed into a unified format for UI and CLI display.
Unified Quota Logic Summary
| Provider | Primary Quota Metric | Reset Characteristic |
|---|---|---|
| Claude | 5-hour and Weekly policy windows | Rolling windows (utilization ratio) |
| Codex | Primary (5h) and Secondary (Weekly) usage | Seconds until reset |
| Gemini | Model-specific buckets (Input/Output) | Fixed reset timestamps |
| GHCP | Interactions, Chat, and Completions | Percent remaining/used |
| Agy | Per-model percentage | Aggregate model averages |
| Sources: src/cliproxy/quota/quota-types.ts:1-240, ui/src/lib/utils.ts:476-525 |
Codex Usage Windows
Codex (ChatGPT) quotas are organized into categories including core usage, code-review, and additional limits (e.g., specific features like Spark). The system prioritizes core usage windows to calculate the "glanceable" account health.
Sources: src/cliproxy/quota/quota-fetcher-codex.ts:109-142, ui/src/lib/utils.ts:246-340
Account Management & Failover
The QuotaManager implements an adaptive pre-flight check to ensure the selected account has sufficient capacity. If an account falls below a configured exhaustion_threshold (default 5%), the system automatically rotates to a healthy alternative.
Pre-flight Check Logic
The pre-flight process ensures high session reliability by enforcing cooldowns on exhausted accounts.
Tier Priority & Cooldowns
Accounts are selected based on a configurable tier_priority (default: ultra > pro > free). When an account is exhausted, it is placed on an in-memory cooldownMap for a specified period (default 5 minutes).
Sources: src/cliproxy/quota/quota-manager.ts:153-200, src/cliproxy/quota/quota-manager.ts:335-360
Visualizations and UI Integration
The analytics interface uses specific color palettes and utility functions to render quota data clearly.
Quota Status Colors
| Status | Hex Code | Purpose |
|---|---|---|
| Success | #15803d | Sufficient quota remaining |
| Degraded | #b45309 | Warning threshold reached |
| Failed | #b91c1c | Quota exhausted or API error |
| Sources: ui/src/lib/utils.ts:36-40 |
Reset Time Formatting
The system adaptively formats reset horizons. If a reset is more than 24 hours away (common for weekly limits), it displays an absolute date. For shorter durations, it displays relative time (e.g., "in 5h 20m").
Sources: ui/src/lib/utils.ts:98-125
Error Handling and Diagnostics
The getQuotaFailureInfo utility maps various API failure states into actionable UI badges.
Structured Failure Info Structure
| Field | Description |
|---|---|
| label | Short badge text (e.g., "Reauth", "Capacity") |
| actionHint | User-facing remediation steps |
| technicalDetail | HTTP status and internal error codes |
| tone | Visual severity (warning, muted, destructive) |
| Sources: ui/src/lib/utils.ts:544-551 |
Conclusion
The Quota & Cost Analytics system provides a robust middleware layer that protects users from provider-side interruptions. By abstracting diverse rate-limiting models into a unified manager with caching, tier-based failover, and detailed diagnostics, CCS ensures consistent performance across multiple AI service subscriptions.
Sources: src/cliproxy/quota/quota-manager.ts:1-15, ui/src/lib/utils.ts:662-730