anomalyco / anomalyco/opencode

[FEATURE]: backward compatibility for v1 plugins in v2

Open
#48,138 1 comment 0 reactions 1 assignee View on GitHub

@nexxeln is already working on this.

Since Sep 9, 2026.

Dominant language
TypeScript
Stars
209k
Forks
27.5k
PR merge metrics
PR metrics pending

Description

Feature hasn't been suggested before.
  • I have verified this feature I'm about to request hasn't been suggested before.
Describe the enhancement you want to request

Problem

v2 rejects plugins written for the old API. The loader decodes each module
against a schema that requires export default { id, setup | effect }
(packages/core/src/plugin/module.ts). Pre-v2 plugins export a bare function,
named or default, that returns a hooks object:

export const RtkOpenCodePlugin = async ({ $ }) => ({
  "tool.execute.before": async (input, output) => { /* rewrite output.args */ },
})

These stop loading on upgrade and the only fix is a full rewrite.
Every existing plugin (eg. rtk, herdr, and others) breaks at once.

Using v2 then is pretty annoying as every plugin breaks.

Proposal

Treat this as missing standard behavior: an upgrade path for old plugins,
behind a flag. Add experimental.legacy_plugins, default false.

  • false (default): same reject as today, but the warning names the flag and
    the migration target instead of a bare schema error.
  • true: the plugin loads through a compat adapter. The adapter maps the v1
    hooks that have a v2 equivalent (tool.execute.before, tool.execute.after,
    event) onto ctx.tool.hook / ctx.event.subscribe, and warns about any
    hook it cannot map so the author knows what to change.

It runs only when the modern decode fails, so modern plugins are untouched. The
adapter sits in one file (plugin/legacy.ts) and can be dropped once plugins
move over.

Scope

Full: tool.execute.*. Best effort: event. Warned and skipped: hooks with no
v2 equal. tui-only default plugins stay rejected.

I have a branch off v2 with the change, config wiring, and tests (unit plus
loader integration for both flag states) ready if the approach is approved at
https://github.com/f15u/opencode/tree/feat/legacy-plugin-compat

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.