Skip to content

CLAUDE.md

Latest commit

 

History

History
211 lines (147 loc) · 7.41 KB

CLAUDE.md

File metadata and controls

211 lines (147 loc) · 7.41 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

AIStudioToAPI is a proxy server that exposes Google AI Studio Build App quota as API endpoints compatible with OpenAI, Gemini, and Anthropic API formats. It is not a reverse proxy for the regular AI Studio web UI or AI Studio Playground. The system uses browser automation (Playwright with Camoufox/Firefox) to translate API requests into in-app requests inside a dedicated AI Studio Build App.

Common Commands

Development

npm run dev              # Start dev server with hot reload (server + UI)
npm run dev:server       # Start only the server in dev mode
npm run dev:ui           # Build UI in watch mode

Production

npm start                # Build UI and start production server

Authentication Setup

npm run setup-auth       # Interactive auth setup (launches browser)
npm run save-auth        # Save authentication credentials

Code Quality

npm run lint             # Lint JavaScript and CSS
npm run lint:fix         # Auto-fix linting issues
npm run lint:js          # Lint only JavaScript files
npm run lint:css         # Lint only CSS/Less files
npm run format           # Format all files with Prettier
npm run format:check     # Check formatting without changes

UI Development

npm run build:ui         # Build Vue.js UI for production
npm run preview:ui       # Preview built UI

Architecture

Core System Components

The system follows a modular architecture with clear separation of concerns:

ProxyServerSystem (src/core/ProxyServerSystem.js)

  • Main orchestrator that integrates all modules
  • Manages HTTP/WebSocket servers
  • Coordinates between authentication, browser management, and request handling
  • Entry point: main.js instantiates and starts this system

BrowserManager (src/core/BrowserManager.js)

  • Manages headless Firefox/Camoufox browser instances
  • Implements multi-context architecture: maintains a pool of browser contexts (Map: authIndex -> {context, page, healthMonitorInterval})
  • Handles context switching between different Google accounts
  • Injects and manages the client-side script (build.js) that communicates with AI Studio
  • Supports background context initialization and rebalancing

ConnectionRegistry (src/core/ConnectionRegistry.js)

  • Manages WebSocket connections from browser contexts
  • Routes messages to appropriate MessageQueue instances
  • Implements grace period for reconnection attempts
  • Supports multiple concurrent connections (one per auth context)

RequestHandler (src/core/RequestHandler.js)

  • Processes incoming API requests
  • Coordinates retry logic and account switching
  • Delegates to AuthSwitcher for account management
  • Delegates to FormatConverter for API format translation

AuthSwitcher (src/auth/AuthSwitcher.js)

  • Handles automatic account switching based on:
    • Usage count (SWITCH_ON_USES)
    • Failure threshold (FAILURE_THRESHOLD)
    • Immediate status codes (IMMEDIATE_SWITCH_STATUS_CODES: 429, 503)
  • Manages system busy state during switches

FormatConverter (src/core/FormatConverter.js)

  • Converts between API formats (OpenAI ↔ Gemini ↔ Anthropic)
  • Handles streaming and non-streaming responses

AuthSource (src/auth/AuthSource.js)

  • Loads authentication data from configs/auth/auth-N.json files
  • Validates and deduplicates accounts by email
  • Maintains rotation indices for account switching

Request Flow

  1. Client sends API request (OpenAI/Gemini/Anthropic format) → Express routes
  2. RequestHandler receives request → FormatConverter normalizes to Gemini format
  3. RequestHandler checks ConnectionRegistry for active WebSocket
  4. If no connection: BrowserManager initializes/switches browser context
  5. Request sent via WebSocket to browser context → injected script interacts with AI Studio
  6. Response streams back via WebSocket → FormatConverter translates to requested format
  7. On failure: AuthSwitcher may trigger account switch based on configured thresholds

Multi-Context Architecture

The system maintains multiple browser contexts simultaneously:

  • Each Google account gets its own browser context and page
  • Contexts are initialized on-demand or in background
  • Current account tracked via browserManager.currentAuthIndex
  • Background initialization prevents request delays when switching accounts
  • Context pool rebalancing ensures optimal resource usage

UI Structure

  • Frontend: Vue.js 3 + Element Plus + Vite
  • Location: ui/ directory
  • Build output: ui/dist/ (served by Express)
  • Features: Account management, VNC login, status monitoring, auth file upload/download

Configuration

Environment Variables

Key variables (see .env.example for full list):

  • PORT: API server port (default: 7860)
  • WS_PORT: WebSocket port for browser communication (default: 9998)
  • API_KEYS: Comma-separated API keys for client authentication
  • INITIAL_AUTH_INDEX: Starting account index (default: 0)
  • STREAMING_MODE: "real" or "fake" streaming
  • SWITCH_ON_USES: Auto-switch after N requests (default: 40)
  • FAILURE_THRESHOLD: Switch after N consecutive failures (default: 3)
  • IMMEDIATE_SWITCH_STATUS_CODES: Status codes triggering immediate switch (default: 429,503)
  • HTTP_PROXY/HTTPS_PROXY: Proxy configuration for Google services
  • CAMOUFOX_EXECUTABLE_PATH: Custom browser executable path
  • MAX_CONTEXTS: Maximum number of accounts logged in simultaneously for faster switching (default: 1, memory usage: ~700MB per account)
  • LOG_LEVEL: Set to "DEBUG" for verbose logging

Model Configuration

Edit configs/models.json to customize available models and their settings.

Authentication Files

  • Location: configs/auth/auth-N.json (N = 0, 1, 2, ...)
  • Format: Playwright browser context state (cookies, localStorage, etc.)
  • Generated by: npm run setup-auth or VNC login in Docker

Key Technical Details

Browser Automation

  • Uses Playwright with Camoufox (privacy-focused Firefox fork)
  • Injects build.js script into AI Studio page for WebSocket communication
  • Script location: public/build.js (built from ui/app/)
  • Health monitoring via periodic checks and reconnection logic

WebSocket Communication

  • Browser contexts connect to WebSocket server on WS_PORT
  • Each connection identified by authIndex
  • MessageQueue pattern for request/response correlation
  • Up to 130s total reconnection wait before full recovery (10s grace period + 120s lightweight reconnect timeout)

Account Switching

  • Automatic switching based on usage/failures
  • Supports immediate switching on specific HTTP status codes
  • System busy flag prevents concurrent switches
  • Lightweight reconnect attempts before full context switch

Streaming Modes

  • Real streaming: True SSE streaming from AI Studio
  • Fake streaming: Buffer complete response, then stream to client

Development Notes

Testing

  • Test files in test/ directory
  • Client test scripts in scripts/client/
  • Auth test scripts in scripts/auth/

Linting & Formatting

  • ESLint for JavaScript (includes Vue plugin)
  • Stylelint for CSS/Less
  • Prettier for code formatting
  • Pre-commit hooks via Husky + lint-staged

Docker

  • Dockerfile supports VNC for browser interaction
  • Auth files mounted via volume: /app/configs/auth
  • Environment variables for configuration

Git Workflow

  • Main branch: main