diff --git a/README.md b/README.md index d526208..c7ac461 100644 --- a/README.md +++ b/README.md @@ -59,62 +59,7 @@ 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) - -```bash -# If installed via npm -antigravity-claude-proxy accounts add - -# If using npx -npx antigravity-claude-proxy@latest accounts add - -# If cloned locally -npm run accounts:add -``` - -This opens your browser for Google OAuth. Sign in and authorize access. Repeat for multiple accounts. - -#### Headless Server (Docker, SSH, no desktop) - -```bash -# If installed via npm -antigravity-claude-proxy accounts add --no-browser - -# If using npx -npx antigravity-claude-proxy@latest accounts add -- --no-browser - -# If cloned locally -npm run accounts:add -- --no-browser -``` - -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. - -#### Manage accounts - -```bash -# List all accounts -antigravity-claude-proxy accounts list - -# Verify accounts are working -antigravity-claude-proxy accounts verify - -# Interactive account management -antigravity-claude-proxy accounts -``` - -### 2. Start the Proxy Server +### 1. Start the Proxy Server ```bash # If installed via npm @@ -129,6 +74,34 @@ npm start The server runs on `http://localhost:8080` by default. +### 2. Link Account(s) + +Choose one of the following methods to authorize the proxy: + +#### **Method A: Web Dashboard (Recommended)** + +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. + +#### **Method B: CLI (Desktop or Headless)** + +If you prefer the terminal or are on a remote server: + +```bash +# Desktop (opens browser) +antigravity-claude-proxy accounts add + +# Headless (Docker/SSH) +antigravity-claude-proxy accounts add --no-browser +``` + +> For full CLI account management options, run `antigravity-claude-proxy accounts --help`. + +#### **Method C: Automatic (Antigravity Users)** + +If you have the **Antigravity** app installed and logged in, the proxy will automatically detect your local session. No additional setup is required. + ### 3. Verify It's Working ```bash @@ -145,6 +118,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` @@ -236,18 +221,18 @@ claude ### 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. @@ -267,20 +252,71 @@ When you add multiple accounts, the proxy automatically: Check account status anytime: ```bash +# Web UI: http://localhost:8080/ (Accounts tab) +# 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, and model health. +- **Visual Model Quota**: Track per-model usage and next reset times. +- **Account Management**: Add/remove Google accounts via OAuth without using the CLI. +- **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 | --- @@ -314,6 +350,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 @@ -322,11 +359,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 ``` @@ -338,6 +377,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 @@ -404,4 +444,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) \ No newline at end of file +[![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) diff --git a/images/webui-accounts.png b/images/webui-accounts.png deleted file mode 100644 index c1689d6..0000000 Binary files a/images/webui-accounts.png and /dev/null differ diff --git a/images/webui-dashboard.png b/images/webui-dashboard.png index 5bb1832..6caea31 100644 Binary files a/images/webui-dashboard.png and b/images/webui-dashboard.png differ diff --git a/images/webui-logs.png b/images/webui-logs.png deleted file mode 100644 index 0f85794..0000000 Binary files a/images/webui-logs.png and /dev/null differ diff --git a/images/webui-models.png b/images/webui-models.png deleted file mode 100644 index 8c2ae66..0000000 Binary files a/images/webui-models.png and /dev/null differ diff --git a/images/webui-settings.png b/images/webui-settings.png deleted file mode 100644 index 33b2ebb..0000000 Binary files a/images/webui-settings.png and /dev/null differ diff --git a/public/favicon.svg b/public/favicon.svg new file mode 100644 index 0000000..36dd62c --- /dev/null +++ b/public/favicon.svg @@ -0,0 +1,10 @@ + + + + + + + + + AG + diff --git a/public/index.html b/public/index.html index 5c01db3..c948359 100644 --- a/public/index.html +++ b/public/index.html @@ -5,6 +5,7 @@ Antigravity Console +