my-pal-mcp-server/docs/antigravity_provider.md

# Antigravity Provider

The Antigravity provider enables access to Claude, Gemini, and other models through Google's unified gateway API. This provides an alternative way to access high-quality models using Google OAuth2 authentication instead of individual API keys.

## Important Warning

> **Terms of Service Risk**: Using the Antigravity provider may violate Google's Terms of Service. Users have reported account bans when using this approach.
>
> **High-Risk Scenarios**:
> - Fresh Google accounts have a very high chance of getting banned
> - New accounts with Pro/Ultra subscriptions are frequently flagged
>
> **By using this provider, you acknowledge and accept all associated risks.**

## Available Models

### Antigravity Quota Pool

These models use the Antigravity unified gateway quota:

| Model ID | Description | Thinking Support |
|----------|-------------|------------------|
| `claude-opus-4-5-thinking` | Claude Opus 4.5 with extended thinking | Yes (up to 32K tokens) |
| `claude-sonnet-4-5-thinking` | Claude Sonnet 4.5 with extended thinking | Yes (up to 32K tokens) |
| `claude-sonnet-4-5` | Claude Sonnet 4.5 standard | No |
| `gemini-3-pro-high` | Gemini 3 Pro with high thinking budget | Yes (up to 65K tokens) |
| `gemini-3-pro-low` | Gemini 3 Pro with low thinking budget | Yes (up to 16K tokens) |
| `gemini-3-flash` | Gemini 3 Flash | Yes (up to 32K tokens) |
| `gpt-oss-120b-medium` | GPT-OSS 120B | No |

### Gemini CLI Quota Pool

These models use a separate Gemini CLI quota:

| Model ID | Description | Thinking Support |
|----------|-------------|------------------|
| `gemini-3-flash-preview` | Gemini 3 Flash Preview | Yes |
| `gemini-3-pro-preview` | Gemini 3 Pro Preview | Yes |
| `gemini-2.5-pro` | Gemini 2.5 Pro | Yes |
| `gemini-2.5-flash` | Gemini 2.5 Flash | Yes |

## Setup

### Option 1: OpenCode Integration (Recommended)

If you use OpenCode with the `opencode-antigravity-auth` plugin, your accounts are automatically detected from:

```
~/.config/opencode/antigravity-accounts.json
```

No additional configuration is needed. The PAL MCP server will automatically discover and use these accounts.

### Option 2: Manual Refresh Token

Set the refresh token directly via environment variable:

```bash
export ANTIGRAVITY_REFRESH_TOKEN="your_oauth_refresh_token"
export ANTIGRAVITY_PROJECT_ID="your_gcp_project_id"  # Optional
```

### Option 3: Custom Accounts File

Create `~/.config/opencode/antigravity-accounts.json` manually:

```json
{
  "version": 3,
  "accounts": [
    {
      "email": "your.email@gmail.com",
      "refreshToken": "1//your_refresh_token_here",
      "projectId": "your-gcp-project-id",
      "enabled": true
    }
  ],
  "activeIndex": 0
}
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ANTIGRAVITY_REFRESH_TOKEN` | No* | OAuth2 refresh token (overrides accounts file) |
| `ANTIGRAVITY_PROJECT_ID` | No | Google Cloud project ID (defaults to `rising-fact-p41fc`) |
| `ANTIGRAVITY_BASE_URL` | No | API endpoint (defaults to production `cloudcode-pa.googleapis.com`) |

*Either `ANTIGRAVITY_REFRESH_TOKEN` or a valid accounts file at `~/.config/opencode/antigravity-accounts.json` is required.

## Features

### Multi-Account Rotation

When multiple accounts are configured, the provider automatically:
- Rotates between accounts when one is rate-limited
- Tracks per-model rate limits separately
- Preserves account preferences for cache efficiency

### Extended Thinking

For models that support thinking (Claude and Gemini 3), you can control the thinking budget:

```python
# Thinking modes: minimal, low, medium, high, max
response = provider.generate_content(
    prompt="Explain quantum computing",
    model_name="claude-opus-4-5-thinking",
    thinking_mode="high"  # Uses 67% of max thinking budget
)
```

| Mode | Budget Percentage |
|------|-------------------|
| minimal | 0.5% |
| low | 8% |
| medium | 33% (default) |
| high | 67% |
| max | 100% |

### Image Support

Models with vision capability support image inputs:

```python
response = provider.generate_content(
    prompt="What's in this image?",
    model_name="gemini-3-flash",
    images=["/path/to/image.png"]
)
```

## Troubleshooting

### "No Antigravity accounts configured"

Ensure either:
1. `ANTIGRAVITY_REFRESH_TOKEN` environment variable is set, or
2. `~/.config/opencode/antigravity-accounts.json` exists with valid accounts

### "All Antigravity accounts are rate limited"

The provider has exhausted all available accounts. Either:
1. Wait for rate limits to reset (usually 60 seconds to a few minutes)
2. Add more accounts to the accounts file

### "Token refresh failed"

Your refresh token may have expired. Re-authenticate:
1. If using OpenCode: `opencode auth login`
2. If manual: Obtain a new refresh token via OAuth2 flow

### 403 Permission Denied

Your Google Cloud project may not have the required APIs enabled:
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Enable the **Gemini for Google Cloud API** (`cloudaicompanion.googleapis.com`)

## API Format

The Antigravity API uses Gemini-style request format internally:

```json
{
  "project": "your-project-id",
  "model": "claude-opus-4-5-thinking",
  "request": {
    "contents": [
      {"role": "user", "parts": [{"text": "Your prompt"}]}
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 8192,
      "thinkingConfig": {
        "thinkingBudget": 8000,
        "includeThoughts": true
      }
    }
  }
}
```

This transformation is handled automatically by the provider.

## Related Resources

- [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) - OpenCode plugin for Antigravity authentication
- [Antigravity API Specification](https://github.com/NoeFabris/opencode-antigravity-auth/blob/dev/docs/ANTIGRAVITY_API_SPEC.md) - Detailed API documentation