Quick start

Step 1: Create your config file

If this is your first time using Opencode, create the config directory first:

mkdir -p ~/.config/opencode

Then create or edit the config file at ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-antigravity-auth"]
}

Note: You can also use a project-local .opencode.json file in your project root instead. The global config at ~/.config/opencode/opencode.json applies to all projects.

Step 2: Authenticate

Run the authentication command:

opencode auth login

1. Select Google as the provider
2. Select OAuth with Google (Antigravity)
3. Project ID prompt: You'll see this prompt:

   Project ID (leave blank to use your default project):
   

   Just press Enter to skip this — it's optional and only needed if you want to use a specific Google Cloud project. Most users can leave it blank.
4. Sign in via the browser and return to Opencode. If the browser doesn't open, copy the displayed URL manually.
5. After signing in, you can add more Google accounts (up to 10) for load balancing, or press Enter to finish.

Alternative: For a quick single-account setup without project ID options, open opencode and use the /connect command instead.

Step 3: Add the models you want to use

Open the same config file you created in Step 1 (~/.config/opencode/opencode.json) and add the models under provider.google.models:

{
  "plugin": ["opencode-antigravity-auth@1.1.3"],
  "provider": {
    "google": {
      "models": {
        "gemini-3-pro-high": {
          "name": "Gemini 3 Pro High (Antigravity)",
          "limit": {
            "context": 1048576,
            "output": 65535
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "gemini-3-pro-low": {
          "name": "Gemini 3 Pro Low (Antigravity)",
          "limit": {
            "context": 1048576,
            "output": 65535
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "gemini-3-flash": {
          "name": "Gemini 3 Flash (Antigravity)",
          "limit": {
            "context": 1048576,
            "output": 65536
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-sonnet-4-5": {
          "name": "Claude Sonnet 4.5 (Antigravity)",
          "limit": {
            "context": 200000,
            "output": 64000
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-sonnet-4-5-thinking": {
          "name": "Claude Sonnet 4.5 Thinking (Antigravity)",
          "limit": {
            "context": 200000,
            "output": 64000
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "claude-opus-4-5-thinking": {
          "name": "Claude Opus 4.5 Thinking (Antigravity)",
          "limit": {
            "context": 200000,
            "output": 64000
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "gpt-oss-120b-medium": {
          "name": "GPT-OSS 120B Medium (Antigravity)",
          "limit": {
            "context": 131072,
            "output": 32768
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

Tip: You only need to add the models you plan to use. The example above includes all available models, but you can remove any you don't need. The modalities field enables image and PDF support in the TUI.

Step 4: Use a model

opencode run "Hello world" --model=google/gemini-3-pro-high

Or start the interactive TUI and select a model from the model picker:

opencode

Antigravity + Gemini CLI OAuth Plugin for Opencode

Enable Opencode to authenticate against Antigravity (Google's IDE) via OAuth so you can use Antigravity rate limits and access models like gemini-3.1-pro and claude-opus-4-6-thinking with your Google credentials.

What You Get

• Claude Opus 4.6, Sonnet 4.6 and Gemini 3.1 Pro/Flash via Google OAuth
• Multi-account support — add multiple Google accounts, auto-rotates when rate-limited
• Dual quota system — access both Antigravity and Gemini CLI quotas from one plugin
• Thinking models — extended thinking for Claude and Gemini 3 with configurable budgets
• Google Search grounding — enable web search for Gemini models (auto or always-on)
• Auto-recovery — handles session errors and tool failures automatically
• Plugin compatible — works alongside other OpenCode plugins (oh-my-opencode, dcp, etc.)

Installation

Install the opencode-antigravity-auth plugin and add the Antigravity model definitions to ~/.config/opencode/opencode.json by following: https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/dev/README.md

opencode run "Hello" --model=google/antigravity-claude-opus-4-6-thinking --variant=max

Models

Model Reference

Antigravity quota (default routing for Claude and Gemini):

Gemini CLI quota (separate from Antigravity; used when cli_first is true or as fallback):

Routing Behavior:

• Antigravity-first (default): Gemini models use Antigravity quota across accounts.
• CLI-first (cli_first: true): Gemini models use Gemini CLI quota first.
• When a Gemini quota pool is exhausted, the plugin automatically falls back to the other pool.
• Claude and image models always use Antigravity. Model names are automatically transformed for the target API (e.g., antigravity-gemini-3-flash → gemini-3-flash-preview for CLI).

Using variants:

opencode run "Hello" --model=google/antigravity-claude-opus-4-6-thinking --variant=max

For details on variant configuration and thinking levels, see docs/MODEL-VARIANTS.md.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-antigravity-auth@latest"],
  "provider": {
    "google": {
      "models": {
        "antigravity-gemini-3-pro": {
          "name": "Gemini 3 Pro (Antigravity)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingLevel": "low" },
            "high": { "thinkingLevel": "high" }
          }
        },
        "antigravity-gemini-3.1-pro": {
          "name": "Gemini 3.1 Pro (Antigravity)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingLevel": "low" },
            "high": { "thinkingLevel": "high" }
          }
        },
        "antigravity-gemini-3-flash": {
          "name": "Gemini 3 Flash (Antigravity)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "minimal": { "thinkingLevel": "minimal" },
            "low": { "thinkingLevel": "low" },
            "medium": { "thinkingLevel": "medium" },
            "high": { "thinkingLevel": "high" }
          }
        },
        "antigravity-claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6 (Antigravity)",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "antigravity-claude-opus-4-6-thinking": {
          "name": "Claude Opus 4.6 Thinking (Antigravity)",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "gemini-2.5-flash": {
          "name": "Gemini 2.5 Flash (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-3-pro-preview": {
          "name": "Gemini 3 Pro Preview (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-3.1-pro-preview": {
          "name": "Gemini 3.1 Pro Preview (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-3.1-pro-preview-customtools": {
          "name": "Gemini 3.1 Pro Preview Custom Tools (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        }
      }
    }
  }
}

Multi-Account Setup

Add multiple Google accounts for higher combined quotas. The plugin automatically rotates between accounts when one is rate-limited.

opencode auth login  # Run again to add more accounts

Account management options (via opencode auth login):

• Configure models — Auto-configure all plugin models in opencode.json
• Check quotas — View remaining API quota for each account
• Manage accounts — Enable/disable specific accounts for rotation

For details on load balancing, dual quota pools, and account storage, see docs/MULTI-ACCOUNT.md.

Troubleshoot

Quick Reset: Most issues can be resolved by deleting ~/.config/opencode/antigravity-accounts.json and running opencode auth login again.

Configuration Path (All Platforms)

OpenCode uses ~/.config/opencode/ on all platforms including Windows.

Windows users: ~ resolves to your user home directory (e.g., C:\Users\YourName). Do NOT use %APPDATA%.

Custom path: Set OPENCODE_CONFIG_DIR environment variable to use a custom location.

Windows migration: If upgrading from plugin v1.3.x or earlier, the plugin will automatically find your existing config in %APPDATA%\opencode\ and use it. New installations use ~/.config/opencode/.

Multi-Account Auth Issues

If you encounter authentication issues with multiple accounts:

1. Delete the accounts file:

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

2. Re-authenticate:

   opencode auth login
   

403 Permission Denied (rising-fact-p41fc)

Error:

Permission 'cloudaicompanion.companions.generateChat' denied on resource 
'//cloudaicompanion.googleapis.com/projects/rising-fact-p41fc/locations/global'

Cause: Plugin falls back to a default project ID when no valid project is found. This works for Antigravity but fails for Gemini CLI models.

Solution:

1. Go to Google Cloud Console
2. Create or select a project
3. Enable the Gemini for Google Cloud API (cloudaicompanion.googleapis.com)
4. Add projectId to your accounts file:

   {
     "accounts": [
       {
         "email": "your@email.com",
         "refreshToken": "...",
         "projectId": "your-project-id"
       }
     ]
   }
   

Note: Do this for each account in a multi-account setup.

Gemini Model Not Found

Add this to your google provider config:

{
  "provider": {
    "google": {
      "npm": "@ai-sdk/google",
      "models": { ... }
    }
  }
}

Gemini 3 Models 400 Error ("Unknown name 'parameters'")

Error:

Invalid JSON payload received. Unknown name "parameters" at 'request.tools[0]'

Causes:

• Tool schema incompatibility with Gemini's strict protobuf validation
• MCP servers with malformed schemas
• Plugin version regression

Solutions:

1. Update to latest beta:

   { "plugin": ["opencode-antigravity-auth@beta"] }
   

2. Disable MCP servers one-by-one to find the problematic one

3. Add npm override:

   { "provider": { "google": { "npm": "@ai-sdk/google" } } }
   

MCP Servers Causing Errors

Some MCP servers have schemas incompatible with Antigravity's strict JSON format.

Common symptom:

Invalid function name must start with a letter or underscore

Sometimes it shows up as:

GenerateContentRequest.tools[0].function_declarations[12].name: Invalid function name must start with a letter or underscore

This usually means an MCP tool name starts with a number (for example, a 1mcp key like 1mcp_*). Rename the MCP key to start with a letter (e.g., gw) or disable that MCP entry for Antigravity models.

Diagnosis:

1. Disable all MCP servers in your config
2. Enable one-by-one until error reappears
3. Report the specific MCP in a GitHub issue

"All Accounts Rate-Limited" (But Quota Available)

Cause: Cascade bug in clearExpiredRateLimits() in hybrid mode (fixed in recent beta).

Solutions:

1. Update to latest beta version
2. If persists, delete accounts file and re-authenticate
3. Try switching account_selection_strategy to "sticky" in antigravity.json

Session Recovery

If you encounter errors during a session:

1. Type continue to trigger the recovery mechanism
2. If blocked, use /undo to revert to pre-error state
3. Retry the operation

Using with Oh-My-OpenCode

Important: Disable the built-in Google auth to prevent conflicts:

// ~/.config/opencode/oh-my-opencode.json
{
  "google_auth": false,
  "agents": {
    "frontend-ui-ux-engineer": { "model": "google/antigravity-gemini-3-pro" },
    "document-writer": { "model": "google/antigravity-gemini-3-flash" }
  }
}

Infinite .tmp Files Created

Cause: When account is rate-limited and plugin retries infinitely, it creates many temp files.

Workaround:

1. Stop OpenCode
2. Clean up: rm ~/.config/opencode/*.tmp
3. Add more accounts or wait for rate limit to expire

OAuth Callback Issues

# Find process using the port
lsof -i :51121

# Kill if stale
kill -9 <PID>

# Retry
opencode auth login

netstat -ano | findstr :51121
taskkill /PID <PID> /F
opencode auth login

ssh -L 51121:localhost:51121 user@remote

Configuration Key Typo: plugin not plugins

The correct key is plugin (singular):

{
  "plugin": ["opencode-antigravity-auth@beta"]
}

Not "plugins" (will cause "Unrecognized key" error).

Migrating Accounts Between Machines

When copying antigravity-accounts.json to a new machine:

1. Ensure the plugin is installed: "plugin": ["opencode-antigravity-auth@beta"]
2. Copy ~/.config/opencode/antigravity-accounts.json
3. If you get "API key missing" error, the refresh token may be invalid — re-authenticate

Known Plugin Interactions

For details on load balancing, dual quota pools, and account storage, see docs/MULTI-ACCOUNT.md.

Plugin Compatibility

@tarquinen/opencode-dcp

DCP creates synthetic assistant messages that lack thinking blocks. List this plugin BEFORE DCP:

{
  "plugin": [
    "opencode-antigravity-auth@latest",
    "@tarquinen/opencode-dcp@latest"
  ]
}

oh-my-opencode

Disable built-in auth and override agent models in oh-my-opencode.json:

{
  "google_auth": false,
  "agents": {
    "frontend-ui-ux-engineer": { "model": "google/antigravity-gemini-3-pro" },
    "document-writer": { "model": "google/antigravity-gemini-3-flash" },
    "multimodal-looker": { "model": "google/antigravity-gemini-3-flash" }
  }
}

Tip: When spawning parallel subagents, enable pid_offset_enabled: true in antigravity.json to distribute sessions across accounts.

Plugins you don't need

• gemini-auth plugins — Not needed. This plugin handles all Google OAuth.

Configuration

Create ~/.config/opencode/antigravity.json for optional settings:

{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json"
}

Most users don't need to configure anything — defaults work well.

Model Behavior

Account Rotation

Quota Protection

How it works: Quota cache is refreshed automatically after API requests (when older than quota_refresh_interval_minutes) and manually via "Check quotas" in opencode auth login. The threshold check uses soft_quota_cache_ttl_minutes to determine cache freshness - if cache is older, the account is considered "unknown" and allowed (fail-open). When ALL accounts exceed the threshold, the plugin waits for the earliest quota reset time (like rate limit behavior). If wait time exceeds max_rate_limit_wait_seconds, it errors immediately.

Rate Limit Scheduling

Control how the plugin handles rate limits:

When to use each mode:

• cache_first (default): Best for long conversations. Waits for the same account to recover, preserving your prompt cache.
• balance: Best for quick tasks. Switches accounts immediately when rate-limited for maximum availability.
• performance_first: Best for many short requests. Distributes load evenly across all accounts.

App Behavior

For all options, see docs/CONFIGURATION.md.

Environment variables:

OPENCODE_CONFIG_DIR=/path/to/config opencode  # Custom config directory
OPENCODE_ANTIGRAVITY_DEBUG=1 opencode         # Enable debug file logging
OPENCODE_ANTIGRAVITY_DEBUG=2 opencode         # Verbose debug file logging
OPENCODE_ANTIGRAVITY_DEBUG_TUI=1 opencode     # Enable TUI log panel debug output

Troubleshooting

See the full Troubleshooting Guide for solutions to common issues including:

• Auth problems and token refresh
• "Model not found" errors
• Session recovery
• Gemini CLI permission errors
• Safari OAuth issues
• Plugin compatibility
• Migration guides

Documentation

• Configuration — All configuration options
• Multi-Account — Load balancing, dual quota pools, account storage
• Model Variants — Thinking budgets and variant system
• Troubleshooting — Common issues and fixes
• Architecture — How the plugin works
• API Spec — Antigravity API reference

Support

If this plugin helps you, consider supporting its maintenance:

Credits

• opencode-gemini-auth by @jenslys
• CLIProxyAPI

License

MIT License. See LICENSE for details.