antigravity-claude-proxy 1.2.16 → 2.0.1

package/README.md

@@ -59,75 +59,54 @@ npm start
 
 ## Quick Start
 
-### 1. Add Account(s)
-
-You have two options:
-
-**Option A: Use Antigravity (Single Account)**
-
-If you have Antigravity installed and logged in, the proxy will automatically extract your token. No additional setup needed.
-
-**Option B: Add Google Accounts via OAuth (Recommended for Multi-Account)**
-
-Add one or more Google accounts for load balancing.
-
-#### Desktop/Laptop (with browser)
+### 1. Start the Proxy Server
 
 ```bash
 # If installed via npm
-antigravity-claude-proxy accounts add
+antigravity-claude-proxy start
 
 # If using npx
-npx antigravity-claude-proxy@latest accounts add
+npx antigravity-claude-proxy@latest start
 
 # If cloned locally
-npm run accounts:add
+npm start
 ```
 
-This opens your browser for Google OAuth. Sign in and authorize access. Repeat for multiple accounts.
+The server runs on `http://localhost:8080` by default.
 
-#### Headless Server (Docker, SSH, no desktop)
+### 2. Link Account(s)
 
-```bash
-# If installed via npm
-antigravity-claude-proxy accounts add --no-browser
+Choose one of the following methods to authorize the proxy:
 
-# If using npx
-npx antigravity-claude-proxy@latest accounts add -- --no-browser
+#### **Method A: Web Dashboard (Recommended)**
 
-# If cloned locally
-npm run accounts:add -- --no-browser
-```
+1. With the proxy running, open `http://localhost:8080` in your browser.
+2. Navigate to the **Accounts** tab and click **Add Account**.
+3. Complete the Google OAuth authorization in the popup window.
 
-This displays an OAuth URL you can open on another device (phone/laptop). After signing in, copy the redirect URL or authorization code and paste it back into the terminal.
+#### **Method B: CLI (Desktop or Headless)**
 
-#### Manage accounts
+If you prefer the terminal or are on a remote server:
 
 ```bash
-# List all accounts
-antigravity-claude-proxy accounts list
-
-# Verify accounts are working
-antigravity-claude-proxy accounts verify
+# Desktop (opens browser)
+antigravity-claude-proxy accounts add
 
-# Interactive account management
-antigravity-claude-proxy accounts
+# Headless (Docker/SSH)
+antigravity-claude-proxy accounts add --no-browser
 ```
 
-### 2. Start the Proxy Server
+> For full CLI account management options, run `antigravity-claude-proxy accounts --help`.
 
-```bash
-# If installed via npm
-antigravity-claude-proxy start
+#### **Method C: Automatic (Antigravity Users)**
 
-# If using npx
-npx antigravity-claude-proxy@latest start
+If you have the **Antigravity** app installed and logged in, the proxy will automatically detect your local session. No additional setup is required.
 
-# If cloned locally
-npm start
-```
+To use a custom port:
 
-The server runs on `http://localhost:8080` by default.
+```bash
+PORT=3001 antigravity-claude-proxy start
+```
 
 ### 3. Verify It's Working
 
@@ -145,6 +124,18 @@ curl "http://localhost:8080/account-limits?format=table"
 
 ### 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`
@@ -261,18 +252,18 @@ Then run `claude` for official API or `claude-antigravity` for this proxy.
 
 ### Claude Models
 
-| Model ID | Description |
-|----------|-------------|
+| 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 |
+| `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 |
+| 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.
@@ -289,23 +280,74 @@ When you add multiple accounts, the proxy automatically:
 - **Invalid account detection**: Accounts needing re-authentication are marked and skipped
 - **Prompt caching support**: Stable session IDs enable cache hits across conversation turns
 
-Check account status anytime:
+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
+antigravity-claude-proxy accounts list
+
+# Verify account health
+antigravity-claude-proxy accounts verify
+
+# Interactive CLI menu
+antigravity-claude-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).
+
+![Antigravity 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.
+- **Claude CLI Configuration**: Edit your `~/.claude/settings.json` directly from the browser.
+- **Live Logs**: Stream server logs with level-based filtering and search.
+- **Advanced Tuning**: Configure retries, timeouts, and debug mode on the fly.
+- **Bilingual Interface**: Full support for English and Chinese (switch via Settings).
+
+---
+
+## 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
+
+- **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`.
+- **Load Balancing**: Adjust `defaultCooldownMs` and `maxWaitBeforeErrorMs`.
+- **Persistence**: Enable `persistTokenCache` to save OAuth sessions across restarts.
+
+Refer to `config.example.json` for a complete list of fields and documentation.
+
 ---
 
 ## 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 |
+| 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                                                   |
 
 ---
 
@@ -339,6 +381,7 @@ npm run test:caching       # Prompt caching
 ### "Could not extract token from Antigravity"
 
 If using single-account mode with Antigravity:
+
 1. Make sure Antigravity app is installed and running
 2. Ensure you're logged in to Antigravity
 
@@ -347,11 +390,13 @@ Or add accounts via OAuth instead: `antigravity-claude-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
 antigravity-claude-proxy accounts
 ```
@@ -363,6 +408,7 @@ With multiple accounts, the proxy automatically switches to the next available a
 ### Account Shows as "Invalid"
 
 Re-authenticate the account:
+
 ```bash
 antigravity-claude-proxy accounts
 # Choose "Re-authenticate" for the invalid account
@@ -412,6 +458,63 @@ By using this software, you acknowledge and accept the following:
 
 ---
 
+## 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/badri-s2001/antigravity-claude-proxy.git
+cd antigravity-claude-proxy
+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:
@@ -429,4 +532,4 @@ MIT
 
 ## Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left&cache-control=no-cache)](https://www.star-history.com/#badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left)
+[![Star History Chart](https://api.star-history.com/svg?repos=badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left&cache-control=no-cache)](https://www.star-history.com/#badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antigravity-claude-proxy",
-  "version": "1.2.16",
+  "version": "2.0.1",
   "description": "Proxy server to use Antigravity's Claude models with Claude Code CLI",
   "main": "src/index.js",
   "type": "module",
@@ -9,11 +9,16 @@
   },
   "files": [
     "src",
-    "bin"
+    "bin",
+    "public"
   ],
   "scripts": {
+    "build:css": "tailwindcss -i ./public/css/src/input.css -o ./public/css/style.css --minify",
+    "watch:css": "tailwindcss -i ./public/css/src/input.css -o ./public/css/style.css --watch",
+    "prepare": "npm run build:css",
     "start": "node src/index.js",
     "dev": "node --watch src/index.js",
+    "dev:full": "concurrently \"npm run watch:css\" \"npm run dev\"",
     "accounts": "node src/cli/accounts.js",
     "accounts:add": "node src/cli/accounts.js add",
     "accounts:list": "node src/cli/accounts.js list",
@@ -52,8 +57,17 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "async-mutex": "^0.5.0",
     "better-sqlite3": "^12.5.0",
     "cors": "^2.8.5",
     "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@tailwindcss/forms": "^0.5.7",
+    "autoprefixer": "^10.4.16",
+    "concurrently": "^8.2.2",
+    "daisyui": "^4.12.14",
+    "postcss": "^8.4.32",
+    "tailwindcss": "^3.4.0"
   }
 }

package/public/app.js

@@ -0,0 +1,198 @@
+/**
+ * Antigravity Console - Main Entry
+ *
+ * This file orchestrates Alpine.js initialization.
+ * Components are loaded via separate script files that register themselves
+ * to window.Components before this script runs.
+ */
+
+document.addEventListener('alpine:init', () => {
+    // Register Components (loaded from separate files via window.Components)
+    Alpine.data('dashboard', window.Components.dashboard);
+    Alpine.data('models', window.Components.models);
+    Alpine.data('accountManager', window.Components.accountManager);
+    Alpine.data('claudeConfig', window.Components.claudeConfig);
+    Alpine.data('logsViewer', window.Components.logsViewer);
+
+    // View Loader Directive
+    Alpine.directive('load-view', (el, { expression }, { evaluate }) => {
+        if (!window.viewCache) window.viewCache = new Map();
+
+        // Evaluate the expression to get the actual view name (removes quotes)
+        const viewName = evaluate(expression);
+
+        if (window.viewCache.has(viewName)) {
+            el.innerHTML = window.viewCache.get(viewName);
+            Alpine.initTree(el);
+            return;
+        }
+
+        fetch(`views/${viewName}.html?t=${Date.now()}`)
+            .then(response => {
+                if (!response.ok) throw new Error(`HTTP ${response.status}`);
+                return response.text();
+            })
+            .then(html => {
+                // Update cache (optional, or remove if we want always-fresh)
+                // keeping cache for session performance, but initial load will now bypass browser cache
+                window.viewCache.set(viewName, html);
+                el.innerHTML = html;
+                Alpine.initTree(el);
+            })
+            .catch(err => {
+                console.error('Failed to load view:', viewName, err);
+                el.innerHTML = `<div class="p-4 border border-red-500/50 bg-red-500/10 rounded-lg text-red-400 font-mono text-sm">
+                    Error loading view: ${viewName}<br>
+                    <span class="text-xs opacity-75">${err.message}</span>
+                </div>`;
+            });
+    });
+
+    // Main App Controller
+    Alpine.data('app', () => ({
+        get connectionStatus() {
+            return Alpine.store('data')?.connectionStatus || 'connecting';
+        },
+        get loading() {
+            return Alpine.store('data')?.loading || false;
+        },
+
+        init() {
+            console.log('App controller initialized');
+
+            // Theme setup
+            document.documentElement.setAttribute('data-theme', 'black');
+            document.documentElement.classList.add('dark');
+
+            // Chart Defaults
+            if (typeof Chart !== 'undefined') {
+                Chart.defaults.color = window.utils.getThemeColor('--color-text-dim');
+                Chart.defaults.borderColor = window.utils.getThemeColor('--color-space-border');
+                Chart.defaults.font.family = '"JetBrains Mono", monospace';
+            }
+
+            // Start Data Polling
+            this.startAutoRefresh();
+            document.addEventListener('refresh-interval-changed', () => this.startAutoRefresh());
+
+            // Initial Fetch
+            Alpine.store('data').fetchData();
+        },
+
+        refreshTimer: null,
+
+        fetchData() {
+            Alpine.store('data').fetchData();
+        },
+
+        startAutoRefresh() {
+            if (this.refreshTimer) clearInterval(this.refreshTimer);
+            const interval = parseInt(Alpine.store('settings')?.refreshInterval || 60);
+            if (interval > 0) {
+                this.refreshTimer = setInterval(() => Alpine.store('data').fetchData(), interval * 1000);
+            }
+        },
+
+        t(key) {
+            return Alpine.store('global')?.t(key) || key;
+        },
+
+        async addAccountWeb(reAuthEmail = null) {
+            const password = Alpine.store('global').webuiPassword;
+            try {
+                const urlPath = reAuthEmail
+                    ? `/api/auth/url?email=${encodeURIComponent(reAuthEmail)}`
+                    : '/api/auth/url';
+
+                const { response, newPassword } = await window.utils.request(urlPath, {}, password);
+                if (newPassword) Alpine.store('global').webuiPassword = newPassword;
+
+                const data = await response.json();
+
+                if (data.status === 'ok') {
+                    // Show info toast that OAuth is in progress
+                    Alpine.store('global').showToast(Alpine.store('global').t('oauthInProgress'), 'info');
+
+                    // Open OAuth window
+                    const oauthWindow = window.open(data.url, 'google_oauth', 'width=600,height=700,scrollbars=yes');
+
+                    // Poll for account changes instead of relying on postMessage
+                    // (since OAuth callback is now on port 51121, not this server)
+                    const initialAccountCount = Alpine.store('data').accounts.length;
+                    let pollCount = 0;
+                    const maxPolls = 60; // 2 minutes (2 second intervals)
+                    let cancelled = false;
+
+                    // Show progress modal
+                    Alpine.store('global').oauthProgress = {
+                        active: true,
+                        current: 0,
+                        max: maxPolls,
+                        cancel: () => {
+                            cancelled = true;
+                            clearInterval(pollInterval);
+                            Alpine.store('global').oauthProgress.active = false;
+                            Alpine.store('global').showToast(Alpine.store('global').t('oauthCancelled'), 'info');
+                            if (oauthWindow && !oauthWindow.closed) {
+                                oauthWindow.close();
+                            }
+                        }
+                    };
+
+                    const pollInterval = setInterval(async () => {
+                        if (cancelled) {
+                            clearInterval(pollInterval);
+                            return;
+                        }
+
+                        pollCount++;
+                        Alpine.store('global').oauthProgress.current = pollCount;
+
+                        // Check if OAuth window was closed manually
+                        if (oauthWindow && oauthWindow.closed && !cancelled) {
+                            clearInterval(pollInterval);
+                            Alpine.store('global').oauthProgress.active = false;
+                            Alpine.store('global').showToast(Alpine.store('global').t('oauthWindowClosed'), 'warning');
+                            return;
+                        }
+
+                        // Refresh account list
+                        await Alpine.store('data').fetchData();
+
+                        // Check if new account was added
+                        const currentAccountCount = Alpine.store('data').accounts.length;
+                        if (currentAccountCount > initialAccountCount) {
+                            clearInterval(pollInterval);
+                            Alpine.store('global').oauthProgress.active = false;
+
+                            const actionKey = reAuthEmail ? 'accountReauthSuccess' : 'accountAddedSuccess';
+                            Alpine.store('global').showToast(
+                                Alpine.store('global').t(actionKey),
+                                'success'
+                            );
+                            document.getElementById('add_account_modal')?.close();
+
+                            if (oauthWindow && !oauthWindow.closed) {
+                                oauthWindow.close();
+                            }
+                        }
+
+                        // Stop polling after max attempts
+                        if (pollCount >= maxPolls) {
+                            clearInterval(pollInterval);
+                            Alpine.store('global').oauthProgress.active = false;
+                            Alpine.store('global').showToast(
+                                Alpine.store('global').t('oauthTimeout'),
+                                'warning'
+                            );
+                        }
+                    }, 2000); // Poll every 2 seconds
+                } else {
+                    Alpine.store('global').showToast(data.error || Alpine.store('global').t('failedToGetAuthUrl'), 'error');
+                }
+            } catch (e) {
+                Alpine.store('global').showToast(Alpine.store('global').t('failedToStartOAuth') + ': ' + e.message, 'error');
+            }
+        }
+    }));
+});