OAuth Plugin for Opencode with Gemini

1.4.10 verified Sat Apr 25 auth: no javascript

Opencode-gemini-auth is an open-source plugin (current stable v1.4.10, released 2025) that authenticates the Opencode CLI using your Google account, enabling access to Gemini models including the free tier. It spins up a local OAuth callback server, supports manual URL paste fallback, and provides a `/gquota` command. Actively maintained with frequent releases. Differentiators: eliminates the need for a separate Google AI API key, supports Gemini Code Assist subscriptions via `projectId`, and includes automatic token refresh. Written in TypeScript, ships with types, peer-depends on TypeScript ^5.9.3.

Common errors

error Error: Cannot find module 'opencode' ↓

cause Opencode CLI is not installed or not found in node_modules.

fix

Install Opencode CLI via npm install -g opencode or ensure it's available as a dependency.

error TypeError: plugin is not a function ↓

cause Wrong import style; this package exports a default function, not an object.

fix

Use import plugin from 'opencode-gemini-auth' (default import).

error Error: Missing projectId for Gemini Code Assist ↓

cause Organization-backed subscription requires explicit projectId.

fix

Set projectId in config or environment variable (GOOGLE_CLOUD_PROJECT).

Warnings

breaking Google has stated that using Gemini CLI OAuth with third-party software may violate policy and trigger account restrictions. ↓

fix Use a Gemini API key instead for lower risk, or accept the potential OAuth policy risk.

gotcha OAuth callback local server may fail if port is in use or in headless environments. ↓

fix Manually paste the callback URL or authorization code when prompted.

deprecated The environment variable OPENCODE_GEMINI_PROJECT_ID is deprecated in favor of projectId config option. ↓

fix Use projectId in provider.google.options config or set GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_PROJECT_ID.

Install

npm install opencode-gemini-auth

yarn add opencode-gemini-auth

pnpm add opencode-gemini-auth

Imports

default
wrong
```
const plugin = require('opencode-gemini-auth')
```
correct
```
import plugin from 'opencode-gemini-auth'
```
ESM-only; no CommonJS support. The default export is a function that returns a plugin object.
login
```
import { login } from 'opencode-gemini-auth'
```
Named export for programmatic login. Available since v1.4.0.
getQuota
```
import { getQuota } from 'opencode-gemini-auth'
```
Named export for checking Gemini quota, used internally by /gquota command.

Quickstart

Shows how to install and authenticate the plugin to use Gemini models with Opencode CLI.

// Ensure Opencode CLI is installed
// Add plugin to Opencode config (~/.config/opencode/opencode.json):
// {
//   "$schema": "https://opencode.ai/config.json",
//   "plugin": ["opencode-gemini-auth@latest"]
// }

// Then run:
// opencode auth login
// Select "Google" then "OAuth with Google (Gemini CLI)"
// Browser will open for OAuth consent