DOCSEARCHbyAlgolia
Submit Docs

Claude Code Hub

repository·main·Indexed 25 days ago

https://github.com/ding113/claude-code-hub

A high-performance AI API proxy and relay platform for teams to manage multiple LLM providers (Claude, OpenAI, Gemini, etc.) through a unified, observable, and scalable gateway. Built with Next.js 15, Hono, PostgreSQL, and Redis, it features intelligent load balancing with circuit breaking, real-time monitoring, and a Management REST API v1.

Tokens
32.1K
Snippets
54
Records
198
Agent score
85%

What's inside claude-code-hub

  1. Overview of Claude Code Hub (CCH)

    main

    Claude Code Hub (CCH) is an intelligent AI API proxy platform designed for agile development teams and AI-driven development workflows. It acts as a server-deployed, multi-tenant scheduling platform that provides unified access to multiple AI providers (such as Claude, Codex, Gemini, and OpenAI-compatible APIs) with intelligent load balancing and automatic failover.

    Key Capabilities:

    • Multi-provider management: Centralized control of various AI providers.
    • High Availability: Automatic switching between providers and circuit breaker functionality with recovery.
    • Session Stickiness: Implements 5-minute context caching to improve cache hits and reduce costs for AI coding tools.
    • Observability: Complete request logging, billing/cost tracking, and session details.
    • Seamless Experience: Zero local configuration required for end users; all provider scheduling is handled by the CCH server.

  2. Overview of Claude Code Hub

    main
    Claude Code Hub is an intelligent AI API proxy and relay platform designed for teams. It provides a unified interface for multiple AI providers (Claude, OpenAI, Gemini, etc.), featuring intelligent load balancing, real-time monitoring, price management, and automated documentation. It is built using Next.js 15, Hono, PostgreSQL, and Redis.

  3. Use the Public Status API to monitor system health

    main

    Claude Code Hub provides two unauthenticated public endpoints for monitoring system status, building external dashboards, or lightweight monitoring integrations. These endpoints return only public-safe fields and do not expose internal provider names, endpoints, or raw error details.

    Endpoints:

    • GET /api/public-status: Returns a public status projection with support for filtering and searching.
    • GET /api/public-site-meta: Returns site metadata like title, description, and timezone.

    Documentation Access:

    • OpenAPI JSON: /api/actions/openapi.json
    • Swagger UI: /api/actions/docs
    • Scalar UI: /api/v1/scalar

  4. Technology Stack Overview

    main

    Claude Code Hub is built using the following technology stack:

    • Framework: Next.js 15 (utilizing SSR and integrated API routes)
    • Router: Hono (optimized for performance)
    • ORM: Drizzle (provides type safety and direct SQL capabilities)
    • Database: PostgreSQL (chosen for reliability and JSON support)
    • Cache: Redis (utilizing data structures and Lua scripting)
    • UI Library: shadcn/ui (customizable and lightweight)

  5. Understand the Claude Code Hub Technology Stack

    main

    Claude Code Hub uses a modern full-stack architecture designed for high performance and self-hosting:

    • Frontend: Next.js 15 (App Router), React 19, Tailwind CSS, and shadcn/ui. Key libraries include next-intl (i18n), zustand (state), recharts (charts), and lucide-react (icons).
    • Backend: Hono for ultra-fast routing, Next.js API Routes, and Server Actions for type-safe RPC. It uses undici for high-performance HTTP requests and zod for validation.
    • Database: PostgreSQL with Drizzle ORM. It supports connection pooling via pg, soft deletes, and JSON columns for flexible data.
    • Caching & Session: Redis (via ioredis) is used for session stickiness (5-minute TTL), distributed rate limiting (Lua scripts), and shared circuit breaker state.
    • Infrastructure: Designed for self-hosting via Docker and Docker Compose, typically involving app, postgres, and redis services.
    • Development: Built with Bun, Turbopack, and TypeScript strict mode.

  6. Core Proxy Engine Capabilities

    main

    The Core Proxy Engine (EPIC-001) provides the foundational routing and transformation logic:

    • Multi-Provider Management: Support for multiple providers with intelligent selection and weighting.
    • Failover & Retries: Automatic retry and failover mechanisms to ensure uninterrupted service.
    • Session Management: Supports session stickiness to maintain conversation context and improve cache hits.
    • Format Conversion: Handles conversion between different API formats to ensure compatibility.

  7. System Architecture Overview of Claude Code Hub

    main

    Claude Code Hub (CCH) is an intelligent AI API proxy platform designed for AI coding tools like Claude Code and Codex. It uses a Modular Monolith architecture built with Next.js 15 (App Router) and Hono.

    The system is designed to provide:

    • Multi-provider management and intelligent load balancing.
    • High Availability via multi-provider failover and circuit breaker patterns.
    • Low Latency through an optimized proxy pipeline and Redis caching.
    • Observability via request logging and real-time dashboards.
    • Extensibility through pluggable provider types and format converters.

  8. Understand Docker data persistence directories

    main

    The project uses a ./data directory to store persistent data for Docker Compose containers. This ensures that data is not lost when containers are rebuilt or restarted.

    • postgres/pgdata/: Stores PostgreSQL database data.
    • redis/: Stores Redis persistence data.

    Important:

    • This directory is not tracked by Git.
    • Backing up this directory is equivalent to backing up all database data.
    • Deleting this directory will wipe all database data.

  9. Claude Code Hub Core Features Overview

    main

    Claude Code Hub is an intelligent AI API relay platform providing:

    • Intelligent Load Balancing: Weight, priority, and grouping scheduler with circuit breakers and up to three failover retries.
    • Multi-provider Management: Support for Claude, Codex, Gemini CLI, and OpenAI-compatible vendors with per-provider model redirection and proxy rules (HTTP/HTTPS/SOCKS).
    • Rate Limiting & Concurrency: Enforces RPM and monetary quotas (5-hour / weekly / monthly) using Redis Lua scripts.
    • OpenAI Compatibility: Supports the /v1/chat/completions endpoint, passing through tool calls and reasoning fields without cross-format conversion.
    • Observability: Real-time monitoring, dashboards, decision-chain tracing, and automated OpenAPI 3.1.0 documentation.

  10. Core Features of Claude Code Hub

    main

    Claude Code Hub provides several key capabilities for managing AI API traffic:

    • Intelligent Load Balancing: Uses weight, priority, and group scheduling with built-in circuit breaking and up to 3 failovers.
    • Multi-Provider Management: Supports Claude, Codex, Gemini CLI, and OpenAI Compatible APIs with custom model redirection and proxy support (HTTP/HTTPS/SOCKS).
    • Rate Limiting & Concurrency Control: Multi-dimensional limits including RPM, budget (5h/week/month), and concurrent sessions using Redis Lua scripts.
    • Automated OpenAPI Documentation: Automatically generates OpenAPI 3.1.0 documentation for 39 REST endpoints.
    • Real-time Monitoring: Dashboard for active sessions, consumption leaderboards, decision chain logs, and proxy status.
    • Session Management: 5-minute context caching and decision chain recording to maintain continuity and auditability.
    • OpenAI Compatibility: Supports /v1/chat/completions with tool calling and reasoning field passthrough without cross-format conversion.

  11. Administration and Monitoring Capabilities

    main

    The Administration Console (EPIC-004) and Monitoring (EPIC-003) provide operational visibility:

    • Real-Time Dashboard: Monitor active sessions and system health.
    • Usage Analytics: View usage statistics and reports by user and time period for cost tracking.
    • Provider Health: Monitor the status of upstream providers.
    • System Configuration: Manage error handling rules (for automatic retries), sensitive word filtering, model pricing, and client versions.

  12. Automatic Failover mechanism

    main

    CCH provides automatic failover to ensure high availability during provider outages. The process works as follows:

    1. A request is sent to CCH and routed to the primary provider.
    2. If the primary provider returns an error, the circuit breaker records the failure.
    3. CCH automatically retries the request on a secondary provider.
    4. If the secondary provider succeeds, the developer receives the response without being aware of the failover.
    5. Once a failure threshold is reached, the circuit breaker opens for the primary provider, and subsequent requests are routed directly to the secondary provider until the primary is deemed healthy again.