Wei-Shaw/claude-relay-service

This system is a multi-provider AI API relay service that proxies requests to platforms such as Claude, Gemini, OpenAI, Azure, Bedrock, and Grok. It provides a unified interface for managing API keys, accounts, and usage quotas, featuring centralized rate limiting, concurrency control, and cost tracking. The system includes a comprehensive CLI and a Vue 3 admin dashboard for operational management, allowing administrators to configure provider connections, monitor usage statistics, and manage user access.

32 changes.

This period established the foundational architecture of the project, introducing a multi-provider AI relay service with Docker deployment, CLI management tools, and comprehensive backend services for account and usage tracking. It also delivered a complete Vue 3 admin single-page application, replacing previous implementations with a modern interface for managing API keys, accounts, and system statistics.

4 changes.

This period focused on expanding the system's support for a diverse range of AI providers, including Claude, Gemini, Azure, Bedrock, and Grok. The work involved implementing dedicated account management, relay services, and scheduling logic to handle varied authentication methods, rate limiting, and routing requirements. Additionally, new administrative SPA utilities were introduced to support real-time feedback and configuration management for these expanded capabilities.

This change introduces the foundational configuration files for the service. config.example.js provides a comprehensive template for server, security, Redis (including TLS), session, Claude API (with dedicated account fallback and rate-limiting controls), Bedrock, proxy, and LDAP settings. config.js defines the available model lists for Claude, Gemini, Grok, OpenAI, and Bedrock, along with helper functions to retrieve them by service. pricingSource.js configures the source for model pricing and context window data, defaulting to a GitHub repository mirror.

config · high confidence

The repository has been initialized with a complete project structure, including a Dockerfile, docker-compose.yml, and a comprehensive .env.example file that documents all configuration options (such as Redis, proxy, and LDAP settings). A new .dockerignore file has been added to exclude development artifacts and sensitive data from Docker builds, and a Makefile has been introduced to standardize common development and deployment tasks like building, testing, and service management.

(repo-wide) · high confidence

The new \src/models/redis.js\ module adds helper functions to calculate date strings, hours, ISO weeks, and custom reset periods (day/hour) based on a configurable system timezone offset, ensuring that usage statistics and cost resets align with user-local time rather than UTC. It also establishes the Redis client connection logic, including TLS support and connection state management, serving as the foundation for the concurrent queue and usage tracking features.

src/models · high confidence

This change adds a new \balanceProviders\ module that enables querying account balances and quotas across multiple AI platforms. It introduces a \BaseBalanceProvider\ abstract class with shared HTTP request handling (including proxy support) and field-based quota fallbacks. Specific providers are implemented for Claude (OAuth usage), Claude Console (field-based), OpenAI Responses (field-based with optional API fallback), and Gemini (Antigravity API integration with quota bucketing). A registration index wires these providers to a central balance service, allowing the system to fetch and normalize balance data from diverse sources using a unified interface.

src/services/balanceProviders · high confidence

This change adds new scheduler classes in src/services/scheduler to handle account selection and routing for specific AI providers. The Droid and Grok schedulers implement logic for binding API keys to dedicated accounts or groups, managing sticky sessions via Redis, and filtering accounts based on health and temporary unavailability. The unified schedulers for Claude, Gemini, and OpenAI provide more complex routing: Claude handles model-specific restrictions (e.g., Opus version access by subscription tier), Gemini supports OAuth provider normalization and API vs. OAuth account separation, and OpenAI includes detailed rate-limit status checking and recovery logic. These files establish the core scheduling infrastructure for these providers, delegating account data retrieval to their respective account services.

src/services/scheduler · high confidence

A new dedicated module, src/handlers/geminiHandlers.js, has been introduced to centralize the logic for processing Gemini API requests. This change consolidates previously scattered handling code into a single location, providing shared functions for building API URLs (supporting both legacy and new template-based base URLs), managing session hashing, and enforcing API key permissions via the unified apiKeyService. By moving these responsibilities into this handler, the system ensures consistent request processing across geminiRoutes.js and standardGeminiRoutes.js, while also integrating upstream error handling and rate-limit tracking directly into the request flow.

src/handlers · high confidence

The admin interface now includes dedicated components for managing user API keys and viewing usage data. Users can create new API keys with names and descriptions via a modal that displays the key for immediate copying. The API key list view allows users to view key details, see usage statistics (requests, tokens, cost), and delete keys if permitted by configuration, with a limit on the number of active keys enforced. Additionally, a usage statistics dashboard provides an overview of total requests, input/output tokens, and costs over selectable time periods.

web/admin-spa/src/components/user · high confidence

Added dedicated request validators for four new CLI clients: Claude Code (validates User-Agent, system prompt similarity, and required headers), Codex CLI (supports vscode, cli\_rs, and exec variants with strict header and body checks on specific paths), Droid CLI (matches factory-cli User-Agent and x-factory-client header), and Gemini CLI (restricts to /gemini paths and validates generateContent User-Agent). These validators ensure that requests originating from these specific command-line tools are correctly identified and routed.

src/validators/clients · high confidence

A new command-line interface (cli/index.js) has been added, providing interactive management capabilities for the system. Users can now create initial administrator accounts (using init.json as the data source), manage API keys (including listing, updating expiry, renewing, and deleting), and manage Amazon Bedrock accounts (listing, creating, editing, toggling status, testing connections, and deleting). The CLI also offers a system status command to view active API keys, active Claude and Bedrock accounts, Redis connection status, and aggregate usage statistics (total tokens and requests).

cli · high confidence

Added new tutorial components in the admin SPA to guide users through installing Node.js and configuring four specific command-line AI tools—Claude Code, Codex, Droid CLI, and Gemini CLI—to connect to the platform's proxy service. These components provide platform-specific instructions (Windows, macOS, Linux) for setting up environment variables, configuration files (such as \config.toml\ and \auth.json\), and API keys, along with verification steps to ensure successful installation.

web/admin-spa/src/components/tutorial · high confidence

The admin interface has been rebuilt as a new Vue 3 single-page application. This version introduces native dark mode support via Element Plus theme variables and integrates vue-i18n for language switching. The application initializes with Pinia for state management, configures Element Plus with Chinese localization by default, and sets up global toast notifications and authentication checks on mount.

web/admin-spa/src · high confidence

The admin SPA now uses a new Vue 3 and Pinia-based architecture to manage application state. This introduces dedicated stores for accounts (supporting platforms like Claude, OpenAI, Bedrock, Gemini, Azure, Droid, and Grok), API keys, API statistics (including multi-key aggregation), authentication, user management, dashboard metrics, settings, and theming (light/dark modes with color schemes). This replaces the previous state management approach to provide a more structured and scalable foundation for the admin interface.

web/admin-spa/src/stores · high confidence

The admin interface now uses a new Vue 3-based layout structure (AppHeader, MainLayout, TabBar) that replaces the previous implementation. The header displays the site logo, version info, and update notifications, while the main layout manages tab-based navigation. The TabBar dynamically adjusts its available tabs based on LDAP configuration: if LDAP is enabled via OEM settings, a 'User Management' tab is added to both the navigation menu and the route mapping; otherwise, it is hidden. This change introduces a new responsive UI with mobile dropdown support and desktop tab buttons, integrating theme toggling and user account management directly into the header.

web/admin-spa/src/components/layout · high confidence

The admin interface now uses a new Vue 3 router configuration that introduces dedicated routes for account management and usage tracking. Users can now access account-specific usage records via the new /accounts/:accountId/usage-records path, in addition to the existing API key usage records at /api-keys/:keyId/usage-records. The router also adds new views for request details (/request-details), quota cards (/quota-cards), and user management (/user-management), while maintaining the existing dashboard, API keys, and settings navigation. Authentication guards have been updated to support both admin and user authentication flows, with separate login paths for each.

web/admin-spa/src/router · high confidence

The admin interface has been rebuilt as a new Vue 3 single-page application (admin-spa). This location introduces the core management views: AccountsView for managing service accounts with platform/group filtering and balance refresh, ApiKeysView for active/deleted key management with tag and model filtering, and ApiStatsView for user-facing usage statistics and quota cards. It also adds AccountUsageRecordsView and ApiKeyUsageRecordsView, which provide detailed, filterable timelines of request usage (including token counts, costs, and cache hits) with CSV export, and BalanceScriptsView for configuring custom scripts to fetch account balances from arbitrary APIs.

web/admin-spa/src/views · high confidence

A new Vue 3 single-page application for the admin interface has been introduced in the \web/admin-spa\ directory, replacing the previous implementation. This update provides a modernized management backend featuring dark mode support via Tailwind CSS, configurable API prefixes, and a new routing structure. The application is built with Vite 5 and includes environment configuration files (\.env.example\, \.env.production\) that allow users to set the base URL (defaulting to \/admin-next/\ in production) and API targets, ensuring the dashboard can be deployed and accessed at the correct path without hardcoding.

web · high confidence

The admin interface now includes several new modal components for the accounts section: AccountBalanceScriptModal allows configuring custom scripts to query account balances; AccountExpiryEditModal provides a dedicated UI for editing account expiration dates; AccountUsageDetailModal displays detailed usage statistics and cost trends; AccountErrorHistoryModal shows recent error logs; AccountScheduledTestModal enables cron-based connectivity tests; and ApiKeyManagementModal offers advanced filtering, searching, and bulk operations for API keys.

web/admin-spa/src/components/accounts · high confidence

This change introduces a comprehensive set of new account services in src/services/account to manage credentials, quotas, and lifecycle for a wide range of AI providers. The new files include accountBalanceService.js for centralized balance tracking, and provider-specific services for Azure OpenAI, Bedrock, CCR, Claude (including OAuth and Console modes), Droid (Factory.ai), Gemini (CLI, API, and Antigravity modes), and Grok (OAuth, official API, and custom endpoints). These services handle secure credential storage (encryption), token refresh, rate limiting, quota management, and account routing, enabling the system to support diverse authentication methods and provider configurations.

src/services/account · high confidence

The admin single-page application now includes dedicated utility modules to support new administrative capabilities. The new \http\_apis.js\ module centralizes API endpoint definitions for managing models, API keys, usage statistics, and account configurations (including Claude, Gemini, OpenAI, and Azure). The \tools.js\ module provides shared UI utilities, including a custom toast notification system, text copying, and formatting functions for numbers, dates, and costs. Additionally, \useTestState.js\ introduces a composable for handling server-sent event (SSE) streams and test request states, enabling real-time feedback for connection tests within the admin interface.

web/admin-spa/src/utils · high confidence

This change introduces a suite of new administrative API routes in src/routes/admin to manage account financial data and organization. The accountBalance.js route provides endpoints to view, refresh, and summarize account balances across platforms, including a summary view for the dashboard and a cache-clearing mechanism. The accountGroups.js route adds full CRUD capabilities for account groups, allowing admins to create, update, and delete groups and view their members across different provider types (Claude, OpenAI, Gemini, etc.). Additionally, balanceScripts.js exposes endpoints to list, save, and test balance calculation scripts, enabling custom logic for balance retrieval. These routes are protected by the authenticateAdmin middleware and integrate with existing services for data retrieval and script execution.

src/routes/admin · high confidence

The admin interface now includes three new components for managing users and inspecting API usage: the ChangeRoleModal allows administrators to modify user roles (user or admin) with safety warnings; the UserUsageStatsModal displays per-user consumption metrics including request counts, token usage, and costs over selectable time periods; and the RequestDetailModal provides a comprehensive view of individual API requests, showing endpoint details, timing, token breakdowns, cost calculations, and request body snapshots.

web/admin-spa/src/components/admin · high confidence

The application now uses a new \src/app.js\ entry point that initializes core services (Redis, pricing, models, admin credentials, cost data) and registers a comprehensive set of route modules (API, admin, web, Gemini, OpenAI, Claude, Droid, Grok, Azure, etc.) along with security and CORS middleware. Additionally, a new CLI tool \src/cli/initCosts.js\ has been added to allow manual initialization of cost data for all API keys via the command line.

src · high confidence

The src/middleware directory now includes a comprehensive auth.js middleware that handles API key extraction, concurrency queue health checks, and rate limiting logic, alongside a new browserFallback.js middleware that specifically supports Chrome extensions and browser-based requests by normalizing headers and user agents to bypass client-side restrictions.

src/middleware · high confidence

Added several new service modules in src/services to support account grouping, name caching, test scheduling, API key indexing, and balance scripts. AccountGroupService introduces account grouping with reverse index migration. AccountNameCacheService provides a 5-minute refresh cache for account and group names. AccountTestSchedulerService enables cron-based account testing. ApiKeyIndexService implements Redis sorted-set indexes for efficient API key pagination and hash\_map rebuilding. BalanceScriptService adds a sandboxed script execution engine with SSRF protection for balance queries. These services collectively enhance account management, performance, and operational capabilities.

src/services · high confidence

The admin interface now includes a suite of reusable Vue components located in \web/admin-spa/src/components/common\. These include \AccountSelector\ for choosing accounts and groups, \ActionDropdown\ for context menus, \ConfirmModal\ for user confirmations, \CustomDropdown\ for general selections, \LogoTitle\ for page headers, \ModelSelector\ for model selection, \StatCard\ for dashboard metrics, \ThemeToggle\ for switching between light/dark modes and color schemes, \ToastNotification\ for system alerts, and \UnifiedTestModal\ for testing API connections. Additionally, \ModelPricingSection\ provides a searchable, sortable table for model pricing data in the settings area.

web/admin-spa/src/components/common · high confidence

The dashboard now includes two new Vue components: ModelDistribution, which displays a doughnut chart and list of model usage statistics with options to toggle between daily and total views, and UsageTrend, which visualizes request and token usage over time using a line chart with adjustable granularity (daily or hourly) and time periods (1, 7, or 30 days). These components integrate with the dashboard store to fetch and display real-time analytics data.

web/admin-spa/src/components/dashboard · high confidence

The application now exposes dedicated routing modules for Azure OpenAI, Droid, Gemini, Grok, OpenAI-to-Claude, and OpenAI-to-Gemini, alongside a comprehensive main API router. These new routes enable the relay of requests to their respective upstream providers (Azure, Anthropic, Google Gemini, xAI Grok, OpenAI) with specific handling for streaming, model mapping, and permission checks. The main API router (\src/routes/api.js\) serves as the central entry point for Claude and Gemini services, featuring enhanced concurrency control, rate-limit tracking, and session validation logic. This change consolidates the request handling infrastructure, allowing the system to support a wider variety of AI providers and client formats (OpenAI-compatible, native Anthropic, native Gemini) through a unified, permission-gated interface.

src/routes · high confidence

This update introduces a suite of new CLI scripts in the \scripts/\ directory to improve operational control and data integrity. The \manage.sh\ and \manage.js\ scripts provide a unified interface for installing, starting, stopping, and restarting the service, including daemon mode support and PID file management. Data management is enhanced with \data-transfer.js\ and \data-transfer-enhanced.js\ for exporting and importing API keys, accounts, and usage stats (with encryption and sanitization support), while \migrate-apikey-expiry.js\ and \fix-usage-stats.js\ allow administrators to backfill missing expiry dates and correct token count inconsistencies in Redis. Additionally, \manage-session-windows.js\ helps debug and restore Claude account session windows, and \debug-redis-keys.js\ / \check-redis-keys.js\ provide visibility into Redis key structures and types.

scripts · high confidence

The relay service layer has been expanded with new dedicated relay implementations for several additional AI providers. The diff introduces \antigravityRelayService.js\ (proxying to Gemini via Antigravity), \azureOpenaiRelayService.js\ (handling Azure OpenAI deployments and API versions), \bedrockRelayService.js\ (supporting AWS Bedrock with Bearer Token auth and region caching), \ccrRelayService.js\ (forwarding to CCR API endpoints), \claudeConsoleRelayService.js\ (managing Claude Console accounts with concurrency limits), \droidRelayService.js\ (proxying to Factory AI's Droid agent), \geminiRelayService.js\ (converting OpenAI formats to Gemini API), and \grokRelayService.js\ (handling xAI Grok with OAuth and API key modes). These services integrate with existing account, scheduler, and rate-limiting infrastructure to support a broader range of upstream providers.

src/services/relay · high confidence

The src/utils directory now includes several new modules that enhance usage tracking, debugging capabilities, and model mapping. accountRollingUsage.js provides rolling usage calculations across hourly and daily time windows with cost computation. Multiple dump utilities (anthropicRequestDump.js, anthropicResponseDump.js, antigravityUpstreamDump.js, antigravityUpstreamResponseDump.js) enable request/response logging with sensitive data redaction and size limits. antigravityModel.js handles model name normalization and mapping for Antigravity upstream services. cacheMonitor.js adds cache monitoring with security cleanup and periodic reporting. commonHelper.js consolidates encryption, JSON parsing, and model name normalization utilities. contents.js contains system prompt definitions for Claude Code with similarity matching capabilities.

src/utils · high confidence

The API Key management interface in the admin SPA has been significantly overhauled to support more granular control and better usability. Administrators can now create and edit API keys in bulk via new BatchApiKeyModal and BatchEditApiKeyModal components, which allow applying tag changes (add, remove, replace), rate limits, and service multipliers to multiple keys at once. The creation flow now supports batch generation with automatic naming suffixes and includes a secure preview/download step for the generated keys. Existing single-key creation and editing modals have been updated to include tag management, owner reassignment, and custom service rate multipliers. Additionally, a new ExpiryEditModal provides intuitive controls for setting expiration dates, including activation-based expiry and quick-select options. Usage limits (daily, opus, window, total) are now visualized using new LimitBadge and LimitProgressBar components that display real-time consumption against configured caps with color-coded progress indicators.

web/admin-spa/src/components/apikeys · high confidence

The API stats page in the admin SPA has been rebuilt with a new UI and expanded capabilities. Users can now query usage statistics for multiple API keys simultaneously (up to 30 keys) via a new multi-key mode, which provides aggregated summaries of total requests, tokens, and costs. The dashboard now includes dedicated components for viewing usage distribution by key, detailed model-level statistics (including input/output/cache tokens and per-model costs), and service-level cost breakdowns that distinguish between official API rates and configured service multipliers. Additionally, the interface displays per-key limits (daily, total, and weekly Claude/Opus costs) and supports dark mode styling.

web/admin-spa/src/components/apistats · high confidence

The client validation logic in src/validators has been updated to include a path whitelist check, ensuring that specific clients (such as Claude Code, Gemini CLI, Codex CLI, and Droid CLI) can only access their designated API endpoints. This change prevents users from bypassing client restrictions by routing requests through compatible but unauthorized endpoints (e.g., OpenAI-compatible paths). The new clientDefinitions.js and clientValidator.js files define these allowed path prefixes and enforce them during request validation, adding a security layer to client identification.

src/validators · high confidence

The admin SPA now uses a structured CSS asset pipeline (variables, global, components, and main stylesheets) to define the visual theme. This introduces a dark mode that automatically adjusts colors, backgrounds, and borders when the 'dark' class is applied, and includes optimized glassmorphism effects with reduced blur intensity to lower GPU usage. The styles also standardize component appearances (buttons, cards, tabs) and apply responsive adjustments for mobile viewports.

web/admin-spa/src/assets · high confidence

Added comprehensive test coverage for the new account balance service (including local quota calculation, caching, and script-based queries), rolling usage aggregation (5h/1d/7d/30d windows), and per-model rate-limit isolation (ensuring Fable/Opus/Sonnet limits do not disable account-wide scheduling). Also added tests for the concurrency queue's slot acquisition logic, percentile calculations, and exponential backoff, as well as integration tests for the admin API key payload rules, Claude Console account testing, and OpenAI responses configuration serialization.

tests · high confidence

The project now includes \package.json\ and \package-lock.json\ for the main \claude-relay-service\ and \web/admin-spa/package.json\ and \web/admin-spa/package-lock.json\ for the Vue 3 admin interface. The backend specifies Node \>=18 and relies on libraries such as Express, ioredis, AWS SDK (Bedrock), and LDAP for authentication and proxying. The admin frontend uses Vue 3, Element Plus, Vite, and Tailwind CSS, establishing the foundational tooling and runtime requirements for the application.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 25 → 26 (+0.2)
• Rubric changed (rubric-2026.09.12 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 9 → 9 (+0.0)
• Architecture 75 → 74 (-1.6)
• Maturity 57 → 57 (+0.1)
• Readiness 33 → 31 (-1.9)
• Security 47 → 52 (+4.9)
• Accessibility 36 → 36 (+0.0)
• Performance 60 (new)

• Documentation: written for insiders (README.md)
• Hotspot: src/models/redis.js (src/models/redis.js)
• Hotspot: src/routes/admin/grokAccounts.js (src/routes/admin/grokAccounts.js)
• Hotspot: src/routes/admin/usageStats.js (src/routes/admin/usageStats.js)
• Hotspot: src/services/account/grokAccountService.js (src/services/account/grokAccountService.js)
• Hotspot: src/utils/grokQuota.js (src/utils/grokQuota.js)
• Hotspot: web/admin-spa/src/components/common/AccountSelector.vue (web/admin-spa/src/components/common/AccountSelector.vue)
• Hotspot: web/admin-spa/src/views/AccountsView.vue (web/admin-spa/src/views/AccountsView.vue)
• Off-boarding risk: anonymized user #1
• batchGetApiKeyStats (cognitive 20) (src/models/redis.js)
• batchGetApiKeyStats (cyclomatic 20) (src/models/redis.js)
• migrateGlobalStats (cyclomatic 21) (src/models/redis.js)

• Documentation: no licence statement (README.md)
• FunctionTooLong: api.router.post("/v1/messages/count_tokens") (src/routes/api.js)
• FunctionTooLong: apiKeys.router.get("/api-keys") (src/routes/admin/apiKeys.js)
• FunctionTooLong: apiKeys.router.post("/api-keys") (src/routes/admin/apiKeys.js)
• FunctionTooLong: apiKeys.router.post("/api-keys/batch") (src/routes/admin/apiKeys.js)
• FunctionTooLong: apiKeys.router.put("/api-keys/:keyId") (src/routes/admin/apiKeys.js)
• FunctionTooLong: apiKeys.router.put("/api-keys/batch") (src/routes/admin/apiKeys.js)
• FunctionTooLong: apiStats.router.post("/api/batch-stats") (src/routes/apiStats.js)
• FunctionTooLong: apiStats.router.post("/api/user-model-stats") (src/routes/apiStats.js)
• FunctionTooLong: apiStats.router.post("/api/user-stats") (src/routes/apiStats.js)
• FunctionTooLong: claudeRelayConfig.router.put("/claude-relay-config") (src/routes/admin/claudeRelayConfig.js)
• FunctionTooLong: dashboard.router.get("/model-stats") (src/routes/admin/dashboard.js)
• FunctionTooLong: droidAccounts.router.get("/droid-accounts") (src/routes/admin/droidAccounts.js)
• FunctionTooLong: openaiAccounts.router.put("/:id") (src/routes/admin/openaiAccounts.js)
• FunctionTooLong: openaiGeminiRoutes.router.post("/v1/chat/completions") (src/routes/openaiGeminiRoutes.js)
• FunctionTooLong: sync.router.get("/sync/export-accounts") (src/routes/admin/sync.js)
• FunctionTooLong: system.router.get("/check-updates") (src/routes/admin/system.js)
• FunctionTooLong: usageStats.router.get("/account-usage-trend") (src/routes/admin/usageStats.js)
• FunctionTooLong: usageStats.router.get("/accounts/:accountId/usage-history") (src/routes/admin/usageStats.js)
• FunctionTooLong: usageStats.router.get("/accounts/:accountId/usage-records") (src/routes/admin/usageStats.js)
• …and 186 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Wei-Shaw/claude-relay-service was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.