### Build and Start Production Server with Bun

Source: https://github.com/ding113/claude-code-hub/blob/main/README.md

Steps to build the application and start the production server using Bun. Install dependencies, build the project, set necessary environment variables, and then run the start command. Consider enabling AUTO_MIGRATE for the first run.

```bash
bun install
bun run build      # 自动复制 VERSION

# 启动生产服务器：
bun run start
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://github.com/ding113/claude-code-hub/blob/main/AGENTS.md

Install project dependencies using Bun and then start the development server. The dev command includes a preflight check.

```bash
bun install               # Install dependencies
bun run dev               # Run tsgo preflight, then start dev server (port 13500)
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://github.com/ding113/claude-code-hub/blob/main/CLAUDE.md

Install project dependencies and start the development server on port 13500.

```bash
bun install
bun run dev
```

--------------------------------

### Build and Start Production Server

Source: https://github.com/ding113/claude-code-hub/blob/main/CLAUDE.md

Build the project for production and start the production server.

```bash
bun run build
bun run start
```

--------------------------------

### Manual Deployment with Bun

Source: https://github.com/ding113/claude-code-hub/blob/main/README.en.md

Install dependencies, build the project, and start the production server using Bun. Ensure environment variables are exported and databases are accessible.

```bash
bun install
bun run build
```

```bash
bun run start
```

--------------------------------

### Local Development Setup with Make

Source: https://github.com/ding113/claude-code-hub/blob/main/README.md

Commands for setting up and managing the local development environment using Make. 'make dev' starts PostgreSQL, Redis, and the bun dev server. Other commands include 'make db' for databases only, 'make logs' for logs, and 'make clean/reset' for environment management.

```bash
cd dev
make dev

# 常用命令：
# - make db：仅启动数据库与 Redis
# - make logs / make logs-app：快速查看服务日志
# - make clean / make reset：清理或重置环境
# 推荐使用 make migrate、make db-shell 处理数据库变更。
```

--------------------------------

### Build and Start Production Server

Source: https://github.com/ding113/claude-code-hub/blob/main/AGENTS.md

Build the project for production and then start the production server. The build command includes a preflight check.

```bash
bun run build             # Run tsgo preflight, then build for production
bun run start             # Start production server
```

--------------------------------

### cch Configuration File Example

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/k8s-deployment.md

An example of the ~/.config/cch/config file, which is automatically written by the installation script. Configuration is applied with the following priority: CLI parameters > environment variables > config file > default values.

```bash
CCH_NAMESPACE="claude-code-hub"
CCH_IMAGE="ghcr.io/ding113/claude-code-hub:latest"
CCH_DEPLOY_DIR="/home/user/.config/cch"
CCH_RUNTIME="k3s"
CCH_INGRESS_HOST="hub.example.com"
```

--------------------------------

### Start Development Environment with Docker Compose

Source: https://github.com/ding113/claude-code-hub/blob/main/AGENTS.md

Navigate to the 'dev' directory and use 'make' commands to start the development environment. 'make dev' starts all services, while 'make db' starts only database services.

```bash
cd dev && make dev        # Start all services (PG + Redis + app)
cd dev && make db         # Start only database services
```

--------------------------------

### Start Development Environment Services

Source: https://github.com/ding113/claude-code-hub/blob/main/CLAUDE.md

Start all necessary services including PostgreSQL and Redis for local development.

```bash
cd dev && make dev
```

--------------------------------

### Start development server

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/i18n-pr-evidence-2026-01-11.md

Use this command to start the local development server. It is necessary for performing manual spotchecks on different locales.

```bash
bun run dev
```

--------------------------------

### Start Services with Docker Compose

Source: https://github.com/ding113/claude-code-hub/blob/main/README.en.md

Command to start all services defined in the docker-compose.yml file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Environment Variable Configuration Example

Source: https://github.com/ding113/claude-code-hub/blob/main/README.md

Example of setting environment variables for the application. Boolean variables support 'true/false' or '1/0'. Values can be quoted in .env files.

```bash
# 布尔变量支持 `true/false` 或 `1/0`；在 `.env` 文件里写成带引号形式也没问题（dotenv 会解析并去掉引号）。更多字段参考 `.env.example`。
```

--------------------------------

### Install k3s and Deploy Claude Code Hub

Source: https://github.com/ding113/claude-code-hub/blob/main/README.md

Use this command to clone the repository, navigate to the directory, and install k3s along with Claude Code Hub. The '-y' flag confirms all prompts.

```bash
git clone https://github.com/ding113/claude-code-hub.git
cd claude-code-hub
bash scripts/deploy-k8s.sh --install-k3s -y
```

--------------------------------

### Local Development Setup

Source: https://github.com/ding113/claude-code-hub/blob/main/README.en.md

Navigate to the dev folder and use make targets to manage local services like PostgreSQL and Redis, and to run the development server.

```bash
cd dev
make dev
```

```bash
make db
```

```bash
make logs
make logs-app
```

```bash
make clean
make reset
```

```bash
make migrate
make db-shell
```

--------------------------------

### Start Database Services

Source: https://github.com/ding113/claude-code-hub/blob/main/tests/README.md

Launch the necessary database services (PostgreSQL and Redis) using Docker Compose. This is a prerequisite for running integration tests.

```bash
docker compose up -d postgres redis
```

--------------------------------

### Example Public Site Meta Request

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/public-status-api.md

A curl request to the /api/public-site-meta endpoint to retrieve public site metadata.

```bash
curl "http://localhost:23000/api/public-site-meta"
```

--------------------------------

### Proxy Request Headers Example

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

Headers required for making requests to the proxy endpoints. Includes authorization, content type, and optional session/client identifiers.

```text
Authorization: Bearer {api_key}
Content-Type: application/json
x-session-id: {optional_session_id}
x-client-version: {optional_version}
anthropic-version: 2023-06-01
```

--------------------------------

### Prometheus Resource Metrics

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

Example Prometheus metrics for tracking active sessions and connection counts for Redis and the database.

```prometheus
# Resource metrics
cch_active_sessions
cch_redis_connections
cch_db_connections
```

--------------------------------

### Sync Dev Branch and Create Feature Branch

Source: https://github.com/ding113/claude-code-hub/blob/main/CONTRIBUTING.md

Before starting new work, sync with the latest 'dev' branch and create a new feature branch.

```bash
git checkout dev
git pull origin dev
git checkout -b feature/provider-weight-ui
```

--------------------------------

### Example Public Status Request

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/public-status-api.md

Demonstrates a curl request to the /api/public-status endpoint with filtering parameters for group, status, and included fields.

```bash
curl "http://localhost:23000/api/public-status?groupSlug=anthropic&status=failed&include=meta,defaults,groups,timeline"
```

--------------------------------

### Circuit Breaker Configuration Example

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

Defines the configuration parameters for a circuit breaker, specifying failure thresholds, open duration, and success thresholds for state transitions.

```typescript
{
  circuitBreakerFailureThreshold: 5,
  circuitBreakerOpenDuration: 1800000,
  circuitBreakerHalfOpenSuccessThreshold: 2
}
```

--------------------------------

### Provider Adapter Interface and Implementations

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

TypeScript interface for adapting external AI provider requests and responses, along with example implementations for Anthropic, OpenAI, and Gemini.

```typescript
interface ProviderAdapter {
  formatRequest(session: ProxySession): Request;
  parseResponse(response: Response): AsyncGenerator<Chunk>;
  handleError(error: Error): ErrorClassification;
}

// Implementations
class AnthropicAdapter implements ProviderAdapter {}
class OpenAIAdapter implements ProviderAdapter {}
class GeminiAdapter implements ProviderAdapter {}
```

--------------------------------

### Get Usage Logs Batch Action

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/dashboard-logs-callchain.md

Server action to fetch a batch of usage logs. It calls the repository function `findUsageLogsBatch` to retrieve data, likely for infinite scrolling.

```typescript
export async function getUsageLogsBatch(filters: LogsFilters, cursor?: string): Promise<PaginatedResult<UsageLog>> {
  return findUsageLogsBatch(filters, cursor);
}
```

--------------------------------

### Clone and Configure Project (Docker Compose)

Source: https://github.com/ding113/claude-code-hub/blob/main/README.en.md

Steps to clone the project repository and set up the initial environment file for Docker Compose deployment.

```bash
git clone https://github.com/ding113/claude-code-hub.git
cd claude-code-hub
cp .env.example .env
```

--------------------------------

### Download and Run Deployment Script (Linux/macOS - wget)

Source: https://github.com/ding113/claude-code-hub/blob/main/README.en.md

An alternative method to download and execute the automated deployment script for Linux or macOS using wget.

```bash
wget https://raw.githubusercontent.com/ding113/claude-code-hub/main/scripts/deploy.sh
chmod +x deploy.sh
./deploy.sh
```

--------------------------------

### Get Usage Logs Stats Action

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/dashboard-logs-callchain.md

Server action to retrieve statistics for usage logs. It calls the repository function `findUsageLogsStats` to get aggregated data, typically for display in a summary or stats panel.

```typescript
export async function getUsageLogsStats(filters: LogsFilters): Promise<UsageLogsStats> {
  return findUsageLogsStats(filters);
}
```

--------------------------------

### Public Status Endpoint

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/api/v1/README.md

An example of a public endpoint that does not require authentication.

```APIDOC
## GET /api/v1/public/status

### Description
Retrieves the current status of the public API.

### Method
GET

### Endpoint
/api/v1/public/status

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **status** (string) - The current status message.
```

--------------------------------

### Public Status Endpoints

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/api/v1/migration-guide.md

Endpoint to get the public status of the system.

```APIDOC
## GET /api/v1/public/status

### Description
Retrieves the public status of the system. Requires no credentials.

### Method
GET

### Endpoint
/api/v1/public/status

### Response
#### Success Response (200)
- **status** (string) - The public status of the system (e.g., "operational").

#### Response Example
{
  "status": "operational"
}
```

--------------------------------

### 本地构建 Docker 镜像

Source: https://github.com/ding113/claude-code-hub/blob/main/CONTRIBUTING.md

本地执行 Docker Compose 命令来构建项目镜像，用于验证容器化体验。

```bash
docker compose build
```

--------------------------------

### Download and Run Deployment Script (Linux/macOS - curl)

Source: https://github.com/ding113/claude-code-hub/blob/main/README.en.md

Use this command to download and execute the automated deployment script for Linux or macOS using curl.

```bash
curl -fsSL https://raw.githubusercontent.com/ding113/claude-code-hub/main/scripts/deploy.sh -o deploy.sh
chmod +x deploy.sh
./deploy.sh
```

--------------------------------

### Invalid Public Status Request Example

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/public-status-api.md

Demonstrates a curl request to the /api/public-status endpoint with an invalid 'status' parameter.

```bash
curl "http://localhost:23000/api/public-status?status=unknown"
```

--------------------------------

### Download and Run Deployment Script (Windows - PowerShell)

Source: https://github.com/ding113/claude-code-hub/blob/main/README.en.md

Execute this PowerShell command as Administrator to download and run the automated deployment script on Windows.

```powershell
# Download and run the deployment script
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/ding113/claude-code-hub/main/scripts/deploy.ps1" -OutFile "deploy.ps1"
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
."/deploy.ps1"
```

--------------------------------

### Prometheus Request Metrics

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

Example Prometheus metrics for tracking total requests and their duration, categorized by endpoint and status.

```prometheus
# Request metrics
cch_requests_total{endpoint, status}
cch_request_duration_seconds{endpoint}
```

--------------------------------

### Run Full Verification (Requires Database)

Source: https://github.com/ding113/claude-code-hub/blob/main/tests/README.md

Execute the complete test suite, including integration tests, which requires a running database and specific configuration changes.

```bash
# 启动数据库
docker compose up -d postgres redis

# 启用所有测试（修改 vitest.config.ts）
# 然后运行
bun run test
```

--------------------------------

### Prometheus Provider Metrics

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

Example Prometheus metrics for monitoring provider-specific request counts, statuses, and circuit breaker states.

```prometheus
# Provider metrics
cch_provider_requests_total{provider, status}
cch_provider_circuit_state{provider}
```

--------------------------------

### Streaming Response Forwarding

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

Example of forwarding a streaming response from an upstream service by enqueuing chunks from the upstream response body.

```typescript
// Streaming response forwarding
return new Response(
  new ReadableStream({
    async start(controller) {
      for await (const chunk of upstreamResponse.body) {
        controller.enqueue(chunk);
      }
    },
  })
);

```

--------------------------------

### Configure Test Database DSN

Source: https://github.com/ding113/claude-code-hub/blob/main/tests/README.md

Create a .env.test file to specify the Data Source Name (DSN) for the test database. This is optional but recommended for custom configurations.

```bash
echo 'DSN=postgres://postgres:postgres@localhost:5432/claude_code_hub' > .env.test
```

--------------------------------

### Production Build

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/i18n-settings-split.zh-CN.md

Generate a production build of the project using 'bun run build'. This command prepares the application for deployment.

```bash
bun run build
```

--------------------------------

### Proxy Response Headers Example

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

Headers returned in responses from the proxy endpoints. Specifies content type and includes a request identifier.

```text
Content-Type: application/json  (or text/event-stream for streaming)
x-request-id: {request_id}
```

--------------------------------

### Run Pre-commit Checks

Source: https://github.com/ding113/claude-code-hub/blob/main/CLAUDE.md

Execute build, lint, type check, and test commands before committing code.

```bash
bun run build
bun run lint
bun run lint:fix
bun run typecheck
bun run test
```

--------------------------------

### Run Pre-commit Checks

Source: https://github.com/ding113/claude-code-hub/blob/main/AGENTS.md

Before committing, run these commands to ensure code quality and production readiness. Includes build, linting, and type checking.

```bash
bun run build      # Production build
bun run lint       # Biome check
bun run lint:fix   # Biome auto-fix
bun run typecheck  # TypeScript check (uses tsgo)
bun run test       # Run Vitest tests
```

--------------------------------

### 配置环境变量

Source: https://github.com/ding113/claude-code-hub/blob/main/CONTRIBUTING.md

复制示例环境变量文件以创建新的环境变量配置文件。

```bash
cp .env.example .env
```

--------------------------------

### Public Status Response - Invalid Parameters

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/public-status-api.md

An example of an error response from /api/public-status when invalid query parameters are provided, such as an unknown status value.

```json
{
  "error": "Invalid public status query parameters",
  "details": [
    {
      "field": "status",
      "code": "invalid_enum",
      "message": "status must be one of: operational, degraded, failed, no_data",
      "value": "unknown"
    }
  ]
}
```

--------------------------------

### Run Unit Tests

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/i18n-settings-split.zh-CN.md

Execute unit tests for the project using the 'bun run test' command. This verifies the functionality of the code.

```bash
bun run test
```

--------------------------------

### Run i18n Settings Index Modules Load Unit Test

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/i18n-pr-checklist.md

Execute unit tests for the i18n settings index modules loading. This command verifies that modules within the i18n settings index are loaded correctly.

```bash
bunx vitest run tests/unit/i18n/settings-index-modules-load.test.ts
```

--------------------------------

### 创建新功能分支

Source: https://github.com/ding113/claude-code-hub/blob/main/CONTRIBUTING.md

根据需求创建新的分支，用于开发新功能或进行较大改动。

```bash
git checkout -b feature/provider-weight-ui
```

--------------------------------

### Sync Backups to Object Storage

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/k8s-deployment.md

Example crontab entry to synchronize local backups to an S3 bucket daily at 3 AM using aws s3 sync.

```bash
0 3 * * * aws s3 sync ~/backups/claude-code-hub s3://my-bucket/cch-backups/
```

--------------------------------

### 克隆仓库并安装依赖

Source: https://github.com/ding113/claude-code-hub/blob/main/CONTRIBUTING.md

克隆项目仓库，进入目录并安装所需的依赖项。

```bash
git clone https://github.com/ding113/claude-code-hub.git
cd claude-code-hub
bun install
```

--------------------------------

### Lint Project

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/i18n-settings-split.zh-CN.md

Run the project's linter with 'bun run lint'. This checks for code style and potential errors.

```bash
bun run lint
```

--------------------------------

### 同步 dev 分支

Source: https://github.com/ding113/claude-code-hub/blob/main/CONTRIBUTING.md

在开始新工作前，切换到 dev 分支并拉取最新的代码。

```bash
git checkout dev
git pull origin dev
```

--------------------------------

### Example Error Response Format

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/api/v1/README.md

This JSON structure represents a typical error response from the API, adhering to RFC 9457. Frontend applications should use the 'errorCode' and 'errorParams' for localization.

```json
{
  "type": "urn:claude-code-hub:problem:auth.forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Admin access is required.",
  "instance": "/api/v1/providers",
  "errorCode": "auth.forbidden",
  "errorParams": {}
}
```

--------------------------------

### 提交代码更改

Source: https://github.com/ding113/claude-code-hub/blob/main/CONTRIBUTING.md

暂存所有更改，使用 Conventional Commits 格式提交消息，并将更改推送到远程仓库。

```bash
git add .
git commit -m "feat: add provider weight ui"
git push origin feature/provider-weight-ui
```

--------------------------------

### Run Local Checks

Source: https://github.com/ding113/claude-code-hub/blob/main/CONTRIBUTING.md

Execute linting, type checking, and optionally build Docker images locally to verify changes before pushing.

```bash
bun run lint
bun run typecheck
# Run bun run test or relevant scripts when logic changes
docker compose build   # optional, mirrors CI Docker Build Test
```

--------------------------------

### GET /api/public-site-meta

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/public-status-api.md

Retrieves public site metadata including title, description, and timezone, sourced from the public-status projection. It indicates availability and the source of the data, providing a reason if the projection is missing.

```APIDOC
## GET /api/public-site-meta

### Description
Returns public site title, description, and timezone, reading only from the public-status projection.

### Method
GET

### Endpoint
/api/public-site-meta

### Success Response
- **available** (boolean) - Indicates if the metadata is available.
- **siteTitle** (string) - The title of the site.
- **siteDescription** (string) - The description of the site.
- **timeZone** (string) - The timezone of the site.
- **source** (string) - The source of the data (e.g., "projection").
- **reason** (string) - Only present if the projection is missing.

### Response Example (Projection Available)
```json
{
  "available": true,
  "siteTitle": "Claude Code Hub",
  "siteDescription": "Claude Code Hub public status",
  "timeZone": "UTC",
  "source": "projection"
}
```

### Response Example (Projection Missing)
```json
{
  "available": false,
  "siteTitle": null,
  "siteDescription": null,
  "timeZone": null,
  "source": "projection",
  "reason": "projection_missing"
}
```
```

--------------------------------

### Run Unit Tests

Source: https://github.com/ding113/claude-code-hub/blob/main/AGENTS.md

Execute unit tests using Vitest. Options include running tests interactively, generating a coverage report, running a single file, or running a specific test by name.

```bash
bun run test              # Run unit tests (vitest)
bun run test:ui           # Interactive test UI
bun run test:coverage     # Coverage report
bunx vitest run <file>    # Run single test file
bunx vitest run -t "test name"  # Run specific test
```

--------------------------------

### Define Input Validation Schema with Zod

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

Example of using Zod schemas for validating input data, specifically for creating a new provider. Ensures fields like `name` and `url` meet defined criteria.

```typescript
// Zod schemas for all inputs
const createProviderSchema = z.object({
  name: z.string().min(1).max(255),
  url: z.string().url(),
  key: z.string().min(10),
  // ...
});
```

--------------------------------

### Get Usage Log Session ID Suggestions Action

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/dashboard-logs-callchain.md

Server action to provide suggestions for session IDs based on user input. It calls `findUsageLogSessionIdSuggestions` in the repository, applying length constraints and prefix matching.

```typescript
export async function getUsageLogSessionIdSuggestions(term: string): Promise<string[]> {
  const trimmedTerm = term.trim();
  if (trimmedTerm.length < SESSION_ID_SUGGESTION_MIN_LEN) {
    return [];
  }

  const escapedTerm = escapeLike(trimmedTerm);
  const suggestions = await findUsageLogSessionIdSuggestions(escapedTerm);

  // Truncate suggestions if they exceed max length
  return suggestions.map(id => id.length > SESSION_ID_SUGGESTION_MAX_LEN ? id.substring(0, SESSION_ID_SUGGESTION_MAX_LEN) : id);
}
```

--------------------------------

### Database Utility Commands

Source: https://github.com/ding113/claude-code-hub/blob/main/CLAUDE.md

Commands for pushing schema changes (dev only), applying migrations, and opening Drizzle Studio.

```bash
bun run db:push
bun run db:studio
```

--------------------------------

### Manage Claude Code Hub Runtime with cch CLI

Source: https://github.com/ding113/claude-code-hub/blob/main/README.md

Commands to manage the Claude Code Hub deployment after installation. Use 'cch status' to check resources, 'cch update' for rolling updates, 'cch backup' for database backups, 'cch info' for access details, and 'cch doctor' for diagnostics.

```bash
cch status            # 查看 Pod / HPA / 资源
cch update            # 拉新镜像 + 自动迁移 + 滚动更新（失败自动回滚）
cch backup            # 备份 PostgreSQL
cch info              # 显示访问地址 + Admin Token
cch doctor            # 诊断集群与部署状态
```

--------------------------------

### GET /api/public-status

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/public-status-api.md

Retrieves a public status projection with support for window parameters, group filtering, model filtering, status filtering, text search, and field selection. It returns a 200 status code if data is available, even if rebuilding, and uses specific status codes for different scenarios like 'no_snapshot' or service unavailability.

```APIDOC
## GET /api/public-status

### Description
Returns a public status projection, supporting window parameters, group filtering, model filtering, status filtering, text search, and field selection.

### Method
GET

### Endpoint
/api/public-status

### Parameters
#### Query Parameters
- **interval** (integer or string `Xm`) - Optional - Allowed values: `5`, `15`, `30`, `60`. Values outside this set are clamped to the nearest allowed value. Non-numeric syntax returns `400`.
- **rangeHours** (integer) - Optional - Defaults to projection's default value. Clamped to `[1, 168]`. Non-numeric syntax returns `400`.
- **groupSlug** (string) - Optional - Exact filter for a single public group slug.
- **groupSlugs** (string) - Optional - Comma-separated list of public group slugs.
- **model** (string) - Optional - Exact filter for a single public model identifier or display name.
- **models** (string) - Optional - Comma-separated list of public model identifiers or display names.
- **status** (string) - Optional - Comma-separated. Allowed values: `operational`, `degraded`, `failed`, `no_data`.
- **q** (string) - Optional - Text search across public group names, slugs, model display names, and model identifiers.
- **include** (string) - Optional - Comma-separated. Allowed values: `meta`, `defaults`, `groups`, `timeline`. Defaults to all public fields.

### Success Response (200)
- **generatedAt** (string) - Timestamp of when the status was generated.
- **freshUntil** (string) - Timestamp until which the status is considered fresh.
- **status** (string) - Current status: `ready`, `stale`, `rebuilding`, `no_snapshot`, `no_data`.
- **rebuildState** (object) - Information about the rebuild process.
  - **state** (string) - Current state of the rebuild.
  - **hasSnapshot** (boolean) - Indicates if a usable snapshot is available.
  - **reason** (string) - Reason for the rebuild state, if any.
- **defaults** (object) - Default query parameters.
- **resolvedQuery** (object) - The query parameters that were resolved.
- **meta** (object) - Metadata about the site.
- **groups** (array) - List of public groups.

### Response Example (Success)
```json
{
  "generatedAt": "2026-04-23T04:00:00.000Z",
  "freshUntil": "2026-04-23T04:05:00.000Z",
  "status": "ready",
  "rebuildState": {
    "state": "fresh",
    "hasSnapshot": true,
    "reason": null
  },
  "defaults": {
    "intervalMinutes": 5,
    "rangeHours": 24
  },
  "resolvedQuery": {
    "intervalMinutes": 5,
    "rangeHours": 24,
    "groupSlugs": [
      "anthropic"
    ],
    "models": [],
    "statuses": [
      "failed"
    ],
    "q": null,
    "include": [
      "meta",
      "defaults",
      "groups",
      "timeline"
    ]
  },
  "meta": {
    "siteTitle": "Claude Code Hub",
    "siteDescription": "Claude Code Hub public status",
    "timeZone": "UTC"
  },
  "groups": []
}
```

### Response Example (No Snapshot but Rebuilding)
```json
{
  "generatedAt": null,
  "freshUntil": null,
  "status": "no_snapshot",
  "rebuildState": {
    "state": "rebuilding",
    "hasSnapshot": false,
    "reason": null
  },
  "defaults": {
    "intervalMinutes": 5,
    "rangeHours": 24
  },
  "resolvedQuery": {
    "intervalMinutes": 5,
    "rangeHours": 24,
    "groupSlugs": [],
    "models": [],
    "statuses": [],
    "q": null,
    "include": [
      "meta",
      "defaults",
      "groups",
      "timeline"
    ]
  },
  "meta": null,
  "groups": []
}
```

### Error Handling
- **503 Service Unavailable**: Redis or projection read unavailable and cannot degrade to projection-missing semantics.
- **400 Bad Request**: Invalid query parameters.
```

--------------------------------

### Run Quality Checks

Source: https://github.com/ding113/claude-code-hub/blob/main/CLAUDE.md

Perform type checking, linting, and code formatting.

```bash
bun run typecheck
bun run lint
bun run lint:fix
bun run format
```

--------------------------------

### Guard Pipeline Configurations

Source: https://github.com/ding113/claude-code-hub/blob/main/docs/architecture-claude-code-hub-2025-11-29.md

Illustrates two distinct configurations for the Guard Pipeline: a full pipeline for chat requests and a minimal pipeline for count_tokens requests.

```typescript
// Full pipeline for chat requests
const CHAT_PIPELINE = [
  "auth", // API key validation
  "version", // Client version check
  "probe", // Probe request handling
  "session", // Session stickiness
  "sensitive", // Content filtering
  "rateLimit", // Rate limiting
  "provider", // Provider selection
  "messageContext", // Request logging
];

// Minimal pipeline for count_tokens
const COUNT_TOKENS_PIPELINE = ["auth", "version", "probe", "provider"];
```

--------------------------------

### Core Proxy Flow

Source: https://github.com/ding113/claude-code-hub/blob/main/CLAUDE.md

Illustrates the request processing pipeline in the proxy handler, including various guard stages.

```text
Request -> GuardPipeline -> [auth -> sensitive -> client -> model -> version -> probe ->
                            session -> warmup -> requestFilter -> rateLimit ->
                            provider -> providerRequestFilter -> messageContext] ->
           ProxyForwarder -> ProxyResponseHandler -> Response
```