opencode-gemini-auth: Google OAuth for the Opencode CLI

What the plugin actually is

opencode-gemini-auth is a package published to npm and loaded by the Opencode CLI as a plugin. GitHub reports it as a TypeScript project with about 1,757 stars, 119 forks, and 26 open issues, tagged with the topics gemini, opencode, and opencode-plugins, and licensed under MIT. The declared purpose in the repository description is a Gemini auth plugin for opencode.

The runtime shape is small. The package entry points resolve to a bundled dist file with type declarations alongside it, and there are exactly two runtime dependencies: the Opencode plugin SDK and an OAuth toolkit. Build tooling is tsup with TypeScript, and the lockfile is Bun's. The package is ESM only and ships just the dist directory, the readme, and the license.

That dependency list explains most of the design. There is no HTTP client of its own and no local database. The OAuth toolkit handles the authorization flow, the Opencode plugin SDK provides the hooks that register a provider, and everything else is configuration and request shaping.

The readme opens by stating the intent plainly: authenticate the Opencode CLI with a Google account and use an existing Gemini plan and quotas, including the free tier, directly inside Opencode. That framing is what makes the project appealing, and it is also the claim the rest of the file complicates.

The warning that reframes the whole project

The first block of the readme is a warning callout, placed above the pitch, and it changes what the plugin can be expected to do. It states that Google deprecated Gemini Code Assist consumer account access on June 18, 2026. It says the Gemini CLI OAuth flow no longer works for Gemini Code Assist individuals, Google AI Pro, and Google AI Ultra accounts, because Google stopped serving requests for those tiers and removed the login option.

It also states that Gemini Code Assist Standard and Enterprise subscriptions are unchanged, and that the manual API key flow is unaffected. On top of that it records that Google has said using Gemini CLI OAuth with third-party software is a policy-violating use case that may trigger abuse detection or account restrictions, and it recommends that people who want the lowest risk use Opencode with their own Gemini API key instead. Links to the deprecation notice and to a policy discussion thread are provided for both claims.

So the readme holds two positions at once, and it does not pick one. The summary says the plugin enables your existing Gemini plan inside Opencode; the banner says the consumer tiers that would supply that plan stopped serving requests, and that continuing to use the OAuth flow on those tiers may breach Google's stated policy. Anyone reading this should treat the banner as the operative information and the summary as the historical pitch. If you hold a Standard or Enterprise seat, the banner says your path is unchanged. If you are on an individual or AI Pro tier, the banner says the OAuth route is the risky one.

Install and sign in

Prerequisites are listed as two items: the Opencode CLI, and a Google account with access to Gemini. Installation is a config edit rather than a package manager command, which fits how Opencode loads plugins.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-gemini-auth@latest"]
}

The sign-in sequence is a three step path. You run the login command, choose Google from the provider list, then pick the OAuth with Google option.

opencode auth login

A browser window opens for approval. The plugin starts a temporary local server to capture the callback, and the readme covers the failure cases that come with that approach: if the local server cannot bind because the port is in use or because you are on a headless machine, you can paste the callback URL or just the authorization code manually. That fallback matters in containers and over SSH, where the happy path silently fails.

Once authenticated, Opencode routes Gemini requests through the account. There is also a slash command for checking the current Gemini Code Assist quota buckets at any time.

/gquota

One operational note belongs here rather than in a troubleshooting section. The published release notes for recent versions tell users to update by deleting the plugin entry from a cached package file inside the Opencode cache directory and then removing the installed package directory, rather than by running an upgrade command. That means a plugin upgrade is a manual cache operation, and a version bump in the config file is not sufficient on its own.

Project selection and organization accounts

By default the plugin attempts to provision or find a suitable Google Cloud project. When that default is wrong, you can pin one explicitly through the config file or through the environment.

{
  "provider": {
    "google": {
      "options": {
        "projectId": "your-specific-project-id"
      }
    }
  }
}

Three environment variables are accepted for the same purpose: a plugin-specific project id variable, the general Google Cloud project variable, and the conventional project id variant. Offering all three is a compatibility hedge, since different environments in the wild already set one or another of them.

The readme also draws a distinction that is easy to get wrong. It says to configure a project id explicitly if you use an organization-backed Gemini Code Assist subscription, which it names as Standard and Enterprise, or if you use a company, school, or Google Workspace account. It notes that most individual Google accounts should not need this. It then adds that Google AI Plus is not a Gemini Code Assist subscription tier, while still allowing a project id to be set to force a specific project.

That is a useful warning label for the tier confusion that runs through Google's Gemini products. Standard and Enterprise are Code Assist tiers. AI Pro, AI Ultra, and AI Plus are consumer subscriptions, and the warning banner says the consumer tiers no longer serve Code Assist requests at all. If your account is a Workspace account, the default project discovery is the thing most likely to pick the wrong project, so set it yourself.

Curating the model list

The plugin does not decide what appears in the model picker on its own; it defers to Opencode settings. Three settings matter and they behave differently from each other, which the readme spells out.

The whitelist setting shows only the listed model ids. The blacklist setting hides specific ids while leaving the rest of the defaults. The models setting defines or overrides metadata and options, but it does not remove the default models by itself. That third distinction is the one that trips people up: adding a models block expecting it to narrow the picker does not work, and you need a whitelist for that.

{
  "provider": {
    "google": {
      "whitelist": [
        "gemini-2.5-flash",
        "gemini-2.5-pro",
        "gemini-3-flash-preview",
        "gemini-3-pro-preview"
      ]
    }
  }
}

The readme also advises building these lists from the exact model ids reported by the model listing command, rather than from memory. Preview ids in particular move around, and a whitelist that names an id the provider no longer serves turns into an empty or partially empty picker. It closes that section by noting that available model names and previews may change and pointing readers at Google's own documentation for current identifiers.

Thinking configuration across model families

Reasoning controls are configured per model through a thinking config block, and the field names differ by model generation. For the Gemini 3 family the setting is a thinking level with a low or high value. For the Gemini 2.5 family the setting is a thinking budget expressed as a token count. A separate boolean controls whether the model emits its internal thoughts.

{
  "provider": {
    "google": {
      "models": {
        "gemini-3-pro-preview": {
          "options": {
            "thinkingConfig": {
              "thinkingLevel": "high",
              "includeThoughts": true
            }
          }
        },
        "gemini-2.5-flash": {
          "options": {
            "thinkingConfig": {
              "thinkingBudget": 8192,
              "includeThoughts": true
            }
          }
        }
      }
    }
  }
}

If you do not set a thinking config for a model, the plugin leaves that model on default behavior. There is also a small compatibility shim worth knowing about: the plugin accepts request payloads that put the thinking config at the request root and normalizes them into the generation config block before forwarding to Gemini Code Assist. That means a config written the flat way still works, which matters if you are porting requests from a tool that uses the flatter shape.

The two family conventions are the part to internalize. Copying a Gemini 2.5 block onto a Gemini 3 model, or the reverse, produces a config the provider will not honor, and the failure will look like thinking being silently ignored rather than like an error.

Proxies, packaging, and release cadence

Network environments get one explicit hook. A proxy variable can be set before starting Opencode, and it is passed through to the fetch proxy option in Bun's runtime.

OPENCODE_GEMINI_AUTH_PROXY=http://127.0.0.1:8080 opencode

The readme notes that this applies to all four network paths in the plugin: OAuth, token refresh, project and quota lookup, and Gemini request forwarding. That list is the useful detail, since a proxy that covers only the request path but not the token refresh path produces an authentication loop rather than a clean failure.

On packaging, the scripts reveal a deliberate release discipline. Publishing runs the test suite and then a build plus a smoke check that imports the built package in Node, so a broken bundle is caught before it reaches the registry. There is also a maintenance command that pulls a local checkout of the Gemini CLI and a companion command that syncs its version into the plugin.

That sync command explains the release history. Version 1.4.16, published in May 2026, syncs the Gemini CLI version and adds tool call ids. Version 1.4.15 fixes preserving the full OpenCode provider cost shape in the auth loader. Version 1.4.14 fixes the release verification flow.

One timing detail is worth flagging. The most recent release GitHub lists for this project is 1.4.16 from May 2026, while the repository itself was pushed as recently as August 2026 and the readme carries a June 2026 deprecation notice. In other words the newest published version predates the warning banner now at the top of the readme. Changes after that release exist on the default branch but have not been published, so an install that pins the latest published version will not carry the deprecation handling, and a maintainer fix that may already exist on the branch will not reach it.

Editorial conclusion

The interesting part of this repository is the gap between its pitch and its warning banner. The pitch describes a plugin that turns an existing Gemini subscription into an Opencode login, while the banner documents that Google stopped serving exactly those accounts and has called third-party OAuth use against its CLI a policy violation. Both statements sit in the same file, at the top, without the author choosing between them, and the practical reading is that the API key path is now the dependable one and the OAuth path is something to evaluate against your own account and your own tolerance for policy risk.

Frequently asked questions

Official sources

1. jenslys/opencode-gemini-auth on GitHub
2. License: MIT
3. Project website
4. README
5. Releases