commons-proxy 2.0.0

package/README.md

@@ -0,0 +1,757 @@
+# CommonsProxy
+
+[![npm version](https://img.shields.io/npm/v/commons-proxy.svg)](https://www.npmjs.com/package/commons-proxy)
+[![npm downloads](https://img.shields.io/npm/dm/commons-proxy.svg)](https://www.npmjs.com/package/commons-proxy)
+[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://ghcr.io/aryanvbw/commonsproxy)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<a href="https://buymeacoffee.com/badrinarayanans" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50"></a>
+
+A **universal AI proxy server** exposing an **Anthropic-compatible API** backed by **multiple providers** (Google Cloud Code, Anthropic, OpenAI, GitHub Models, GitHub Copilot, OpenRouter), enabling you to use Claude, Gemini, GPT, and more with **Claude Code CLI**.
+
+> 🎉 **v2.0.0 Released**: Now supporting Anthropic, OpenAI, GitHub Models, GitHub Copilot, and OpenRouter in addition to Google Cloud Code!
+
+📚 **Quick Links**: [Installation](#installation) | [Provider Setup](docs/PROVIDERS.md) | [Docker](#option-3-docker-recommended-for-production) | [Contributing](CONTRIBUTING.md)
+
+## How It Works
+
+```
+┌──────────────────┐     ┌─────────────────────┐     ┌─────────────────────────┐
+│   Claude Code    │────▶│    CommonsProxy     │────▶│  Multiple Providers:    │
+│   (Anthropic     │     │   (Universal Router)│     │  • Google Cloud Code    │
+│    API format)   │     │                     │     │  • Anthropic API        │
+└──────────────────┘     └─────────────────────┘     │  • OpenAI API           │
+                                                      │  • GitHub Models        │
+                                                      │  • GitHub Copilot       │
+                                                      │  • OpenRouter            │
+                                                      └─────────────────────────┘
+```
+
+**Request Flow**:
+1. Claude Code CLI sends request in **Anthropic Messages API format**
+2. CommonsProxy routes to appropriate provider based on account configuration
+3. Transforms request to **provider-specific format** (Google Generative AI, Anthropic, OpenAI, GitHub)
+4. Sends to provider's API using OAuth or API Key authentication
+5. Converts response back to **Anthropic format** with full streaming and thinking support
+
+**Key Features**:
+- 🔄 **Multi-Provider Support**: Use Google, Anthropic, OpenAI, GitHub Models, GitHub Copilot, and OpenRouter accounts
+- 🔐 **Flexible Authentication**: OAuth 2.0 (Google), Device Auth (Copilot), or API Keys (others)
+- ⚖️ **Intelligent Load Balancing**: Hybrid/Sticky/Round-Robin strategies
+- 📊 **Real-time Quota Tracking**: Dashboard shows usage across all providers
+- 💾 **Prompt Caching**: Maintains cache continuity with sticky account selection
+- 🎨 **Web Management UI**: Easy account management and monitoring
+
+## 🎯 Supported Providers
+
+| Provider | Auth Method | Available Models | Quota Tracking | Status |
+|----------|-------------|------------------|----------------|--------|
+| **Google Cloud Code** | OAuth 2.0 with PKCE | Claude 3.5 Sonnet/Opus, Gemini 2.0 Flash/Pro | ✅ Real-time via API | ✅ Primary |
+| **Anthropic** | API Key | Claude 3.5 Sonnet/Opus/Haiku | ⚠️ Manual (console) | ✅ Supported |
+| **OpenAI** | API Key | GPT-4 Turbo, GPT-4, GPT-3.5 Turbo | ⚠️ Manual (console) | ✅ Supported |
+| **GitHub Models** | Personal Access Token | GitHub Marketplace models | ⚠️ GitHub API limits | ✅ Supported |
+| **GitHub Copilot** | Device Authorization | GPT-4o, GPT-4, Claude 3.5 Sonnet, o1 | ⚠️ Copilot limits | ✅ Supported |
+| **OpenRouter** | API Key | 100+ models (Claude, GPT, Gemini, Llama, etc.) | ✅ Credit-based | ✅ Supported |
+
+**Quota Tracking Legend**:
+- ✅ **Real-time via API**: CommonsProxy automatically fetches and displays quota in WebUI
+- ⚠️ **Manual**: Check quota limits in the provider's web console
+
+**Custom Endpoints**: OpenAI provider supports custom API endpoints (Azure OpenAI, self-hosted APIs)
+
+📖 **Setup Guides**: See [`docs/PROVIDERS.md`](docs/PROVIDERS.md) for detailed setup instructions for each provider.
+
+## Prerequisites
+
+- **Node.js** 18 or later
+- **Windsurf/Cursor IDE** installed (for single-account mode) OR Google account(s) for multi-account mode
+
+---
+
+## Installation
+
+### Option 1: npm (Recommended)
+
+```bash
+# Run directly with npx (no install needed)
+npx commons-proxy@latest start
+
+# Or install globally
+npm install -g commons-proxy@latest
+commons-proxy start
+```
+
+### Option 2: Clone Repository
+
+```bash
+git clone https://github.com/AryanVBW/CommonsProxy.git
+cd CommonsProxy
+npm install
+npm start
+```
+
+### Option 3: Docker 🐳 (Recommended for Production)
+
+```bash
+# Pull and run from GitHub Container Registry
+docker run -d \
+  --name commons-proxy \
+  -p 8080:8080 \
+  -v ~/.config/commons-proxy:/app/data/.config/commons-proxy \
+  ghcr.io/aryanvbw/commonsproxy:latest
+
+# Or use docker-compose
+curl -O https://raw.githubusercontent.com/AryanVBW/CommonsProxy/main/docker-compose.yml
+docker-compose up -d
+```
+
+**Access WebUI**: Open `http://localhost:8080` to configure accounts
+
+**Environment Variables**:
+```bash
+docker run -d \
+  -p 8080:8080 \
+  -e PORT=8080 \
+  -e DEBUG=true \
+  -e WEBUI_PASSWORD=your-password \
+  -v ~/.config/commons-proxy:/app/data/.config/commons-proxy \
+  ghcr.io/aryanvbw/commonsproxy:latest
+```
+
+---
+
+## Quick Start
+
+### 1. Start the Proxy Server
+
+```bash
+# If installed via npm
+commons-proxy start
+
+# If using npx
+npx commons-proxy@latest start
+
+# If cloned locally
+npm start
+```
+
+The server runs on `http://localhost:8080` by default.
+
+### 2. Link Account(s)
+
+CommonsProxy supports multiple AI providers. Add one or more accounts to get started.
+
+> 💡 **Tip**: You can mix and match providers! Add multiple Google accounts for load balancing, plus Anthropic/OpenAI as fallbacks.
+
+---
+
+#### 🔵 Google Cloud Code (OAuth 2.0)
+
+**Best for**: Claude and Gemini models with real-time quota tracking
+
+**WebUI Setup** (Recommended):
+1. Navigate to `http://localhost:8080` → **Accounts** tab → **Add Account**
+2. Select **Google Cloud Code** from provider dropdown
+3. Complete OAuth authorization in popup window
+
+**CLI Setup**:
+```bash
+# Desktop (opens browser)
+commons-proxy accounts add --provider=google
+
+# Headless server (manual code input)
+commons-proxy accounts add --provider=google --no-browser
+```
+
+**Available Models**: `claude-sonnet-4-5`, `claude-opus-4-5`, `gemini-3-flash`, `gemini-3-pro-low`, `gemini-3-pro-high`
+
+---
+
+#### 🟠 Anthropic (API Key)
+
+**Best for**: Direct Claude API access with official rate limits
+
+**Prerequisites**: Anthropic account at [console.anthropic.com](https://console.anthropic.com), API key with billing enabled
+
+**Setup**:
+1. Get API key: https://console.anthropic.com/settings/keys
+2. In WebUI: **Accounts** → **Add Account** → **Anthropic** → Paste key
+3. Or CLI: `commons-proxy accounts add --provider=anthropic`
+
+**Available Models**: `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022`, `claude-3-opus-20240229`
+
+---
+
+#### 🟢 OpenAI (API Key)
+
+**Best for**: GPT models and Azure OpenAI integration
+
+**Prerequisites**: OpenAI account at [platform.openai.com](https://platform.openai.com), API key with credits
+
+**Setup**:
+1. Get API key: https://platform.openai.com/api-keys
+2. In WebUI: **Accounts** → **Add Account** → **OpenAI** → Paste key
+3. Optional: Enable "Custom Endpoint" for Azure OpenAI
+4. Or CLI: `commons-proxy accounts add --provider=openai`
+
+**Available Models**: `gpt-4-turbo-preview`, `gpt-4`, `gpt-3.5-turbo`
+
+**Azure OpenAI**: Supports custom endpoints for Azure deployments
+
+---
+
+#### 🟣 GitHub Models (Personal Access Token)
+
+**Best for**: Access to GitHub Marketplace models (beta)
+
+**Prerequisites**: GitHub account, Personal Access Token with `read:packages` scope
+
+**Setup**:
+1. Create PAT: https://github.com/settings/tokens
+2. In WebUI: **Accounts** → **Add Account** → **GitHub Models** → Paste token
+3. Or CLI: `commons-proxy accounts add --provider=github`
+
+**Available Models**: GitHub Marketplace models (varies by account/region)
+
+---
+
+📚 **Detailed Guides**: For step-by-step instructions with screenshots and troubleshooting, see:
+- [`docs/PROVIDERS.md`](docs/PROVIDERS.md) - Complete provider setup guides
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Adding new providers
+
+### 3. Verify It's Working
+
+```bash
+# Health check
+curl http://localhost:8080/health
+
+# Check account status and quota limits
+curl "http://localhost:8080/account-limits?format=table"
+```
+
+---
+
+## Using with Claude Code CLI
+
+### Configure Claude Code
+
+You can configure these settings in two ways:
+
+#### **Via Web Console (Recommended)**
+
+1. Open the WebUI at `http://localhost:8080`.
+2. Go to **Settings** → **Claude CLI**.
+3. Select your preferred models and click **Apply to Claude CLI**.
+
+> [!TIP] > **Configuration Precedence**: System environment variables (set in shell profile like `.zshrc`) take precedence over the `settings.json` file. If you use the Web Console to manage settings, ensure you haven't manually exported conflicting variables in your terminal.
+
+#### **Manual Configuration**
+
+Create or edit the Claude Code settings file:
+
+**macOS:** `~/.claude/settings.json`
+**Linux:** `~/.claude/settings.json`
+**Windows:** `%USERPROFILE%\.claude\settings.json`
+
+Add this configuration:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "test",
+    "ANTHROPIC_BASE_URL": "http://localhost:8080",
+    "ANTHROPIC_MODEL": "claude-opus-4-5-thinking",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-5-thinking",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5-thinking",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-4-5",
+    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-5-thinking",
+    "ENABLE_EXPERIMENTAL_MCP_CLI": "true"
+  }
+}
+```
+
+Or to use Gemini models:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "test",
+    "ANTHROPIC_BASE_URL": "http://localhost:8080",
+    "ANTHROPIC_MODEL": "gemini-3-pro-high[1m]",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gemini-3-pro-high[1m]",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gemini-3-flash[1m]",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3-flash[1m]",
+    "CLAUDE_CODE_SUBAGENT_MODEL": "gemini-3-flash[1m]",
+    "ENABLE_EXPERIMENTAL_MCP_CLI": "true"
+  }
+}
+```
+
+### Load Environment Variables
+
+Add the proxy settings to your shell profile:
+
+**macOS / Linux:**
+
+```bash
+echo 'export ANTHROPIC_BASE_URL="http://localhost:8080"' >> ~/.zshrc
+echo 'export ANTHROPIC_AUTH_TOKEN="test"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+> For Bash users, replace `~/.zshrc` with `~/.bashrc`
+
+**Windows (PowerShell):**
+
+```powershell
+Add-Content $PROFILE "`n`$env:ANTHROPIC_BASE_URL = 'http://localhost:8080'"
+Add-Content $PROFILE "`$env:ANTHROPIC_AUTH_TOKEN = 'test'"
+. $PROFILE
+```
+
+**Windows (Command Prompt):**
+
+```cmd
+setx ANTHROPIC_BASE_URL "http://localhost:8080"
+setx ANTHROPIC_AUTH_TOKEN "test"
+```
+
+Restart your terminal for changes to take effect.
+
+### Run Claude Code
+
+```bash
+# Make sure the proxy is running first
+commons-proxy start
+
+# In another terminal, run Claude Code
+claude
+```
+
+> **Note:** If Claude Code asks you to select a login method, add `"hasCompletedOnboarding": true` to `~/.claude.json` (macOS/Linux) or `%USERPROFILE%\.claude.json` (Windows), then restart your terminal and try again.
+
+### Multiple Claude Code Instances (Optional)
+
+To run both the official Claude Code and CommonsProxy version simultaneously, add this alias:
+
+**macOS / Linux:**
+
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+alias claude-commons='CLAUDE_CONFIG_DIR=~/.claude-account-commons ANTHROPIC_BASE_URL="http://localhost:8080" ANTHROPIC_AUTH_TOKEN="test" command claude'
+```
+
+**Windows (PowerShell):**
+
+```powershell
+# Add to $PROFILE
+function claude-commons {
+    $env:CLAUDE_CONFIG_DIR = "$env:USERPROFILE\.claude-account-commons"
+    $env:ANTHROPIC_BASE_URL = "http://localhost:8080"
+    $env:ANTHROPIC_AUTH_TOKEN = "test"
+    claude
+}
+```
+
+Then run `claude` for official API or `claude-commons` for this proxy.
+
+---
+
+## Available Models
+
+### Claude Models
+
+| Model ID                     | Description                              |
+| ---------------------------- | ---------------------------------------- |
+| `claude-sonnet-4-5-thinking` | Claude Sonnet 4.5 with extended thinking |
+| `claude-opus-4-5-thinking`   | Claude Opus 4.5 with extended thinking   |
+| `claude-sonnet-4-5`          | Claude Sonnet 4.5 without thinking       |
+
+### Gemini Models
+
+| Model ID            | Description                     |
+| ------------------- | ------------------------------- |
+| `gemini-3-flash`    | Gemini 3 Flash with thinking    |
+| `gemini-3-pro-low`  | Gemini 3 Pro Low with thinking  |
+| `gemini-3-pro-high` | Gemini 3 Pro High with thinking |
+
+Gemini models include full thinking support with `thoughtSignature` handling for multi-turn conversations.
+
+---
+
+## Multi-Account Load Balancing
+
+When you add multiple accounts, the proxy intelligently distributes requests across them using configurable selection strategies.
+
+### Account Selection Strategies
+
+Choose a strategy based on your needs:
+
+| Strategy | Best For | Description |
+| --- | --- | --- |
+| **Hybrid** (Default) | Most users | Smart selection combining health score, token bucket rate limiting, quota awareness, and LRU freshness |
+| **Sticky** | Prompt caching | Stays on the same account to maximize cache hits, switches only when rate-limited |
+| **Round-Robin** | Even distribution | Cycles through accounts sequentially for balanced load |
+
+**Configure via CLI:**
+
+```bash
+commons-proxy start --strategy=hybrid    # Default: smart distribution
+commons-proxy start --strategy=sticky    # Cache-optimized
+commons-proxy start --strategy=round-robin  # Load-balanced
+```
+
+**Or via WebUI:** Settings → Server → Account Selection Strategy
+
+### How It Works
+
+- **Health Score Tracking**: Accounts earn points for successful requests and lose points for failures/rate-limits
+- **Token Bucket Rate Limiting**: Client-side throttling with regenerating tokens (50 max, 6/minute)
+- **Quota Awareness**: Accounts with critical quota (<5%) are deprioritized; exhausted accounts trigger emergency fallback
+- **Emergency Fallback**: When all accounts appear exhausted, bypasses checks with throttle delays (250-500ms)
+- **Automatic Cooldown**: Rate-limited accounts recover automatically after reset time expires
+- **Invalid Account Detection**: Accounts needing re-authentication are marked and skipped
+- **Prompt Caching Support**: Session IDs derived from conversation enable cache hits across turns
+
+### Monitoring
+
+Check account status, subscription tiers, and quota anytime:
+
+```bash
+# Web UI: http://localhost:8080/ (Accounts tab - shows tier badges and quota progress)
+# CLI Table:
+curl "http://localhost:8080/account-limits?format=table"
+```
+
+#### CLI Management Reference
+
+If you prefer using the terminal for management:
+
+```bash
+# List all accounts
+commons-proxy accounts list
+
+# Verify account health
+commons-proxy accounts verify
+
+# Interactive CLI menu
+commons-proxy accounts
+```
+
+---
+
+## Web Management Console
+
+The proxy includes a built-in, modern web interface for real-time monitoring and configuration. Access the console at: `http://localhost:8080` (default port).
+
+![CommonsProxy Console](images/webui-dashboard.png)
+
+### Key Features
+
+- **Real-time Dashboard**: Monitor request volume, active accounts, model health, and subscription tier distribution.
+- **Visual Model Quota**: Track per-model usage and next reset times with color-coded progress indicators.
+- **Account Management**: Add/remove Google accounts via OAuth, view subscription tiers (Free/Pro/Ultra) and quota status at a glance.
+- **Manual OAuth Mode**: Add accounts on headless servers by copying the OAuth URL and pasting the authorization code.
+- **Claude CLI Configuration**: Edit your `~/.claude/settings.json` directly from the browser.
+- **Persistent History**: Tracks request volume by model family for 30 days, persisting across server restarts.
+- **Time Range Filtering**: Analyze usage trends over 1H, 6H, 24H, 7D, or All Time periods.
+- **Smart Analysis**: Auto-select top 5 most used models or toggle between Family/Model views.
+- **Live Logs**: Stream server logs with level-based filtering and search.
+- **Advanced Tuning**: Configure retries, timeouts, and debug mode on the fly.
+- **Multi-language Interface**: Full support for English, Chinese (中文), Indonesian (Bahasa), and Portuguese (PT-BR).
+
+---
+
+## Advanced Configuration
+
+While most users can use the default settings, you can tune the proxy behavior via the **Settings → Server** tab in the WebUI or by creating a `config.json` file.
+
+### Configurable Options
+
+- **API Key Authentication**: Protect `/v1/*` API endpoints with `API_KEY` env var or `apiKey` in config.
+- **WebUI Password**: Secure your dashboard with `WEBUI_PASSWORD` env var or in config.
+- **Custom Port**: Change the default `8080` port.
+- **Retry Logic**: Configure `maxRetries`, `retryBaseMs`, and `retryMaxMs`.
+- **Rate Limit Handling**: Comprehensive rate limit detection from headers and error messages with intelligent retry-after parsing.
+- **Load Balancing**: Adjust `defaultCooldownMs` and `maxWaitBeforeErrorMs`.
+- **Persistence**: Enable `persistTokenCache` to save OAuth sessions across restarts.
+- **Max Accounts**: Set `maxAccounts` (1-100) to limit the number of Google accounts. Default: 10.
+- **Endpoint Fallback**: Automatic 403/404 endpoint fallback for API compatibility.
+
+Refer to `config.example.json` for a complete list of fields and documentation.
+
+---
+
+## macOS Menu Bar App
+
+For macOS users who prefer a native experience, there's a companion menu bar app that provides quick access to server controls without touching the terminal. Get it from: [commons-proxy-bar](https://github.com/IrvanFza/commons-proxy-bar)
+
+> **Note:** This is a GUI wrapper only. You still need to install and setup the proxy server first using one of the [installation methods](#installation) above.
+
+![AntiGravity Claude Proxy Bar](https://github.com/IrvanFza/commons-proxy-bar/blob/main/images/application.png?raw=true)
+
+### Key Features
+
+- **Server Control**: Start/stop the proxy server with a single click or ⌘S shortcut.
+- **Status Indicator**: Menu bar icon shows server running state at a glance.
+- **WebUI Access**: Open the web management console directly from the menu.
+- **Port Configuration**: Customize the proxy server port (default: 8080).
+- **Auto-Start Options**: Launch server on app start and launch app at login.
+- **Native Experience**: Clean, native SwiftUI interface designed for macOS.
+
+---
+
+## API Endpoints
+
+| Endpoint          | Method | Description                                                           |
+| ----------------- | ------ | --------------------------------------------------------------------- |
+| `/health`         | GET    | Health check                                                          |
+| `/account-limits` | GET    | Account status and quota limits (add `?format=table` for ASCII table) |
+| `/v1/messages`    | POST   | Anthropic Messages API                                                |
+| `/v1/models`      | GET    | List available models                                                 |
+| `/refresh-token`  | POST   | Force token refresh                                                   |
+
+---
+
+## Testing
+
+Run the test suite (requires server running):
+
+```bash
+# Start server in one terminal
+npm start
+
+# Run tests in another terminal
+npm test
+```
+
+Individual tests:
+
+```bash
+npm run test:signatures    # Thinking signatures
+npm run test:multiturn     # Multi-turn with tools
+npm run test:streaming     # Streaming SSE events
+npm run test:interleaved   # Interleaved thinking
+npm run test:images        # Image processing
+npm run test:caching       # Prompt caching
+npm run test:strategies    # Account selection strategies
+npm run test:cache-control # Cache control field stripping
+```
+
+---
+
+## Troubleshooting
+
+### Windows: OAuth Port Error (EACCES)
+
+On Windows, the default OAuth callback port (51121) may be reserved by Hyper-V, WSL2, or Docker. If you see:
+
+```
+Error: listen EACCES: permission denied 0.0.0.0:51121
+```
+
+The proxy will automatically try fallback ports (51122-51126). If all ports fail, try these solutions:
+
+#### Option 1: Use a Custom Port (Recommended)
+
+Set a custom port outside the reserved range:
+
+```bash
+# Windows PowerShell
+$env:OAUTH_CALLBACK_PORT = "3456"
+commons-proxy start
+
+# Windows CMD
+set OAUTH_CALLBACK_PORT=3456
+commons-proxy start
+
+# Or add to your .env file
+OAUTH_CALLBACK_PORT=3456
+```
+
+#### Option 2: Reset Windows NAT
+
+Run as Administrator:
+
+```powershell
+net stop winnat
+net start winnat
+```
+
+#### Option 3: Check Reserved Ports
+
+See which ports are reserved:
+
+```powershell
+netsh interface ipv4 show excludedportrange protocol=tcp
+```
+
+If 51121 is in a reserved range, use Option 1 with a port outside those ranges.
+
+#### Option 4: Permanently Exclude Port (Admin)
+
+Reserve the port before Hyper-V claims it (run as Administrator):
+
+```powershell
+netsh int ipv4 add excludedportrange protocol=tcp startport=51121 numberofports=1
+```
+
+> **Note:** The server automatically tries fallback ports (51122-51126) if the primary port fails.
+
+---
+
+### "Could not extract token from Cloud Code IDE"
+
+If using single-account mode with Windsurf/Cursor:
+
+1. Make sure the IDE is installed and running
+2. Ensure you're logged in with your Google account
+
+Or add accounts via OAuth instead: `commons-proxy accounts add`
+
+### 401 Authentication Errors
+
+The token might have expired. Try:
+
+```bash
+curl -X POST http://localhost:8080/refresh-token
+```
+
+Or re-authenticate the account:
+
+```bash
+commons-proxy accounts
+```
+
+### Rate Limiting (429)
+
+With multiple accounts, the proxy automatically switches to the next available account. With a single account, you'll need to wait for the rate limit to reset.
+
+### Account Shows as "Invalid"
+
+Re-authenticate the account:
+
+```bash
+commons-proxy accounts
+# Choose "Re-authenticate" for the invalid account
+```
+
+---
+
+## Safety, Usage, and Risk Notices
+
+### Intended Use
+
+- Personal / internal development only
+- Respect internal quotas and data handling policies
+- Not for production services or bypassing intended limits
+
+### Not Suitable For
+
+- Production application traffic
+- High-volume automated extraction
+- Any use that violates Acceptable Use Policies
+
+### Warning (Assumption of Risk)
+
+By using this software, you acknowledge and accept the following:
+
+- **Terms of Service risk**: This approach may violate the Terms of Service of AI model providers (Anthropic, Google, etc.). You are solely responsible for ensuring compliance with all applicable terms and policies.
+
+- **Account risk**: Providers may detect this usage pattern and take punitive action, including suspension, permanent ban, or loss of access to paid subscriptions.
+
+- **No guarantees**: Providers may change APIs, authentication, or policies at any time, which can break this method without notice.
+
+- **Assumption of risk**: You assume all legal, financial, and technical risks. The authors and contributors of this project bear no responsibility for any consequences arising from your use.
+
+**Use at your own risk. Proceed only if you understand and accept these risks.**
+
+---
+
+## Legal
+
+- **Not affiliated with Google or Anthropic.** This is an independent open-source project and is not endorsed by, sponsored by, or affiliated with Google LLC or Anthropic PBC.
+
+- "Gemini", "Google Cloud", and "Google" are trademarks of Google LLC.
+
+- "Claude" and "Anthropic" are trademarks of Anthropic PBC.
+
+- Software is provided "as is", without warranty. You are responsible for complying with all applicable Terms of Service and Acceptable Use Policies.
+
+---
+
+## Development
+
+### For Developers & Contributors
+
+This project uses a local Tailwind CSS build system. CSS is pre-compiled and included in the repository, so you can run the project immediately after cloning.
+
+#### Quick Start
+
+```bash
+git clone https://github.com/AryanVBW/CommonsProxy.git
+cd CommonsProxy
+npm install  # Automatically builds CSS via prepare hook
+npm start    # Start server (no rebuild needed)
+```
+
+#### Frontend Development
+
+If you need to modify styles in `public/css/src/input.css`:
+
+```bash
+# Option 1: Build once
+npm run build:css
+
+# Option 2: Watch for changes (auto-rebuild)
+npm run watch:css
+
+# Option 3: Watch both CSS and server (recommended)
+npm run dev:full
+```
+
+**File Structure:**
+- `public/css/src/input.css` - Source CSS with Tailwind `@apply` directives (edit this)
+- `public/css/style.css` - Compiled & minified CSS (auto-generated, don't edit)
+- `tailwind.config.js` - Tailwind configuration
+- `postcss.config.js` - PostCSS configuration
+
+#### Backend-Only Development
+
+If you're only working on backend code and don't need frontend dev tools:
+
+```bash
+npm install --production  # Skip devDependencies (saves ~20MB)
+npm start
+```
+
+**Note:** Pre-compiled CSS is committed to the repository, so you don't need to rebuild unless modifying styles.
+
+#### Project Structure
+
+See [CLAUDE.md](./CLAUDE.md) for detailed architecture documentation, including:
+- Request flow and module organization
+- Frontend architecture (Alpine.js + Tailwind)
+- Service layer patterns (`ErrorHandler.withLoading`, `AccountActions`)
+- Dashboard module documentation
+
+---
+
+## Credits
+
+This project is based on insights and code from:
+
+- [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) - CommonsProxy OAuth plugin for OpenCode
+- [claude-code-proxy](https://github.com/1rgs/claude-code-proxy) - Anthropic API proxy using LiteLLM
+
+---
+
+## License
+
+MIT
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=badrisnarayanan/commons-proxy&type=date&legend=top-left&cache-control=no-cache)](https://www.star-history.com/#badrisnarayanan/commons-proxy&type=date&legend=top-left)