ai-sdk-provider-opencode-sdk weekly downloads statistics

AI SDK Provider for OpenCode

5.x targets OpenCode 2.x. Still running an OpenCode 1.x server? Use the 4.x line: npm install ai-sdk-provider-opencode-sdk@opencode-v1. Not sure which you have? See Which version do I need?

A community provider for the Vercel AI SDK (v7) that runs generations through an OpenCode 2.x server via @opencode/client. OpenCode is an AI coding agent: it owns the model catalog, executes tools server-side, and manages sessions; this provider maps that onto generateText() / streamText() with tool observation, two-phase tool approvals, interactive forms, and native usage/cost metadata.

Which version do I need?

Two things decide it: your AI SDK major version and your OpenCode server major version.

| | OpenCode 2.x | OpenCode 1.x |

| AI SDK v7 | 5.x — npm i ai-sdk-provider-opencode-sdk | 4.x — npm i ai-sdk-provider-opencode-sdk@opencode-v1 | | AI SDK v6 | not supported | 3.x (legacy) — npm i ai-sdk-provider-opencode-sdk@ai-sdk-v6 | | AI SDK v5 | not supported | 0.x (legacy) — npm i ai-sdk-provider-opencode-sdk@ai-sdk-v5 |

Which OpenCode do I have? opencode --version prints opencode v2.x.y on OpenCode 2 and a bare 1.x.y on OpenCode 1. A running 2.x server also answers GET /api/info with its version; a 1.x server has no such route. Note that the npm package opencode-ai is OpenCode 1.x — OpenCode 2.x is published as @opencode/cli.

Version compatibility

| Provider | AI SDK | OpenCode server | npm tag | Branch | Status |

| 5.x | v7 | 2.x (@opencode/cli; tested against 2.0.24) | latest | main | Active | | 4.x | v7 | 1.x (opencode-ai) | opencode-v1 | opencode-v1 | Maintenance | | 3.x | v6 | 1.x | ai-sdk-v6 | ai-sdk-v6 | Legacy | | 2.x, 1.x | v6 | 1.x | — | historical | Legacy | | 0.x | v5 | 1.x | ai-sdk-v5 | ai-sdk-v5 | Legacy |

Maintenance lines get bug fixes; Legacy lines stay installable but receive no further releases.

Upgrading from 4.x? OpenCode 2.x is a new backend, not an SDK bump, and most settings changed — see docs/migrating-v4-to-v5.md and the CHANGELOG.

Server

5.x pins @opencode/client@2.0.24. Run the matching server from the published @opencode/cli (binary opencode, also exposed as opencode2), or use the opencode 2.x binary from the official installer:

serve requires HTTP Basic auth on every route: username opencode, password from OPENCODE_PASSWORD or printed at startup as server password . A server without the 2.x /api/info route (OpenCode 1.x, or the pre-2.0 beta builds) is reported as incompatible on first use.

Requirements

• Node.js >= 22 • An OpenCode 2.x server — npx @opencode/cli@2.0.24 serve (note the package is @opencode/cli, not opencode-ai) • Credentials on that server for the providers you want to use. The OpenCode zen free tier works without credentials on 2.x.

Quick start

The 2.x server requires Basic auth (opencode:) on every route:

Backends

createOpencode selects exactly one backend, in precedence order:

1. client — a caller-supplied OpenCode.make(...) client. Used as-is; the provider never closes it.

2. clientManager — a caller-supplied manager (advanced injection seam; see createClientManagerFromPort). Never disposed by the provider.

3. baseUrl — the provider constructs the client with clientOptions (headers, fetch).

4. Service discovery — Service.discover() via the local registration file, with the registered endpoint's auth merged automatically. opencode serve --service writes $XDG_STATE_HOME/opencode/service.json ({id, version, url, pid, password}) and binds a fixed port (49374). autoStart: true additionally spawns one via Service.ensure, whose default command is opencode serve --service — that opencode must be the 2.x binary (a v1 opencode from opencode-ai has no --service flag), or pass service.command explicitly. Auto-start is opt-in because it leaves a long-lived background service running. The zero-config default provider (import { opencode }) works once a registered service exists.

Every backend runs a connection preflight (server.info + migration.v1.status) on first use; a server without /api/info is reported as an incompatible pre-2.0 build.

Model IDs

Models are providerID/modelID strings from your server's catalog (model.list); a bare modelID omits the model at session create so the server default applies. OpencodeModels exports shortcuts for three OpenCode zen free-tier IDs, each present in a live 2.0.24 catalog and in the upstream models.dev catalog (no credentials needed on 2.x; the free tier churns and catalogs are server-dependent, so any ID your own catalog lists works — the shortcuts are a convenience, not a limit):

Sessions and conversations

OpenCode owns the transcript: model and agent are session state, and a prompt sends only new user text. The binding rule is one model instance = one conversation = one pinned session:

Session state is model-instance-local: the instance creates or pins a session on first use and reuses it for every later call on that instance. Nothing outlives the instance — no session ID is persisted, and each opencode(...) call builds a new model. sessionMode selects which session that is:

• "ephemeral" (default) — the provider creates a session on first use and owns it exclusively (it survives tool-approval round-trips). • "existing" — pin the session given by sessionId (implied when sessionId is set without a mode). Shared-session caveat: OpenCode 2.x has no inbox→execution correlation key, so events from other clients on the same session (e.g. a TUI) can be misattributed to your call. Use exclusively-owned sessions unless you accept that.

For a fresh session on every ordinary call, use createNewSession: true (approval continuations still reattach to the blocked session).

Per call, providerOptions.opencode.sessionId targets an existing session for that one request, and providerOptions.opencode.id sets the prompt's user-message ID (a msg_-prefixed id; when omitted the provider generates one, which it uses to correlate the turn's own events):…

Description from the npm listing.