V2 Plugin API compatibility (OpenCode 2.0)

OpenCode V2 Plugin API Compatibility

The problem

OpenCode 2.0 introduced a breaking change to the plugin API. V1 plugins no longer load in V2 — they fail with:

PluginModule.LoadError: Plugin must export a default definition with an id and an effect or setup function.

This affects all V1-format plugins regardless of how they're configured.

What changed

The default export must now be an object with id and setup (or effect), not a bare async function:

// V1 (no longer works in OpenCode 2.0)
export default async (ctx) => {
  return { /* hooks, tools, etc. */ };
};

// V2 — Promise-based
export default {
  id: "plugin-name",
  setup: async (context) => {
    // context has { client, project, directory, worktree, ... }
    return { /* hooks, tools, etc. */ };
  }
};

// V2 — Effect-based
export default {
  id: "plugin-name",
  effect: (context) => Effect.gen(function* () { ... })
};

The PluginContext in V2 provides the same capabilities (client, project, directory, etc.) — the hooks and tools return format is unchanged.

Migration guide

https://opencode.ai/v2/docs/migrate-v1/

The @opencode-ai/plugin package exports V2 types:

• @opencode-ai/plugin/v2/promise for the Promise-based API
• @opencode-ai/plugin/v2/effect for the Effect-based API

Impact

This plugin currently fails to load on OpenCode 2.0.3+. Any user who has upgraded to OpenCode 2 loses this plugin's functionality until a V2-compatible version is released.

Thanks

Really appreciate the work on this plugin! Happy to help test a V2 release.