Ecosystem Manager

简体中文

A single control plane for the OpenCode plugin ecosystem. Browse the official ecosystem plus the much larger awesome-opencode community list, check V1/V2 compatibility and npm availability, and toggle installs without editing opencode.json(c) by hand.

Why

The OpenCode ecosystem page lists dozens of plugins, but trying one means editing global configuration, remembering which packages you added, and cleaning up manually when an experiment does not work out. Ecosystem Manager keeps that bookkeeping in one place:

• Catalog in the loop. 39 official plugins plus 122 community plugins (161 total) with a short description, V1/V2 compatibility, and npm status.
• Community-aware. Every entry is marked official or awesome-opencode, and the dashboard can filter on either source.
• Per-plugin switches. Turning a switch on installs that package; turning it off uninstalls it.
• Ownership tracking. It only removes packages it installed. Plugins you added yourself are never touched.
• Guarded installs. A package must resolve on npm and be loadable by OpenCode V2 before the switch flips.
• Upgrade checks. Compare installed package plugins with npm, including the manager itself, and upgrade one or all without leaving the tool or dashboard.
• Local dashboard. Search, filter, and toggle from a browser UI bound to 127.0.0.1.
• No JSONC damage. Installs and removals go through opencode plugin add/remove, so comments and unrelated settings survive.

Sources

• Official: https://opencode.ai/docs/ecosystem#plugins
• Community: https://github.com/awesome-opencode/awesome-opencode

The community snapshot is generated by scripts/build-awesome-catalog.mjs. It reads the upstream registry, resolves each project's npm package from its package.json, and records whether the package looks V2-compatible, V1-only, or unverified. Community entries can be V1-only, unpublished, or missing an npm package; those entries stay visible but cannot be switched on.

Requirements

• OpenCode 2.x
• The opencode CLI on PATH, or an OPENCODE_CLI environment variable that points to the binary. The desktop app's bundled CLI is detected automatically.

Install

opencode plugin add opencode-ecosystem-manager

Or add it to ~/.config/opencode/opencode.json(c) manually:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-ecosystem-manager"]
}

Reload OpenCode after installing.

Usage

Ask the agent to call the ecosystem_manager tool, or use the slash command:

/ecosystem ui                   # open the browser dashboard
/ecosystem list                 # catalog, without refreshing npm
/ecosystem check                # refresh npm status, then list
/ecosystem status               # master switch and selected plugins
/ecosystem on opencode-tavily   # enable and install
/ecosystem off opencode-tavily  # disable and uninstall
/ecosystem enable               # enable master switch, install selections
/ecosystem disable              # disable master switch, uninstall managed
/ecosystem sync                 # reconcile config with saved state
/ecosystem updates             # check installed plugins for updates
/ecosystem upgrade             # upgrade every outdated plugin
/ecosystem upgrade opencode-tavily  # upgrade one plugin

on, off, and upgrade accept multiple names at once. Names may be catalog names or npm package names. Packages outside the catalog are also accepted and installed as-is.

Upgrade checks include the manager itself. When it was installed from npm it is just another configured package and can update itself; when it runs from a local directory it is reported as a local build that cannot self-update. Restart OpenCode after a manager self-update.

Dashboard

/ecosystem ui starts a dashboard on 127.0.0.1 (port 47821 when free, otherwise an ephemeral port) and opens it in the default browser. It provides:

• Search and filtering across all 161 official and community entries
• Source filters for official vs community plugins
• Descriptions, V1/V2 compatibility, and live npm status
• Per-plugin switches plus a master switch
• Update checks with per-plugin current → latest versions, one-click upgrade, and an upgrade-all action (the manager is included)
• npm refresh and manual sync
• A one-time access token exchanged for an HttpOnly, SameSite=Strict cookie; API requests also validate Origin

The server lives with the OpenCode process, so the plugin reload triggered by an install or uninstall does not tear down the dashboard. Run /ecosystem ui again after restarting OpenCode.

Safety rules

• Only the global config at ~/.config/opencode/opencode.json is changed, and only through opencode plugin add/remove.
• Only packages recorded as managed in state.json are uninstalled.
• A switch is refused when npm returns 404, the package is deprecated, or the registry cannot be reached.
• Entries marked v1 or none are refused because OpenCode V2 cannot load them. V2 and unverified community packages are allowed; unverified entries carry a warning and may not load.
• Community entries without an npm package are listed but cannot be switched on.
• Upgrade checks cover package plugins in the global config; local, git, and file-based plugins are reported but never updated automatically.
• Turning the master switch off keeps the selection and uninstalls every managed package. Turning it back on reinstalls them.
• State is synchronized about two seconds after load and again after a configuration-triggered reload.

Files and state

• src/index.ts — tool and /ecosystem command registration, auto-sync
• src/manager.ts — reconciliation, update checks, CLI calls, textual output
• src/ui.ts — local HTTP server, tokens, API
• src/ui.html — dashboard
• src/catalog.ts — official catalog plus merge/deduplication logic
• src/awesome-catalog.ts — generated awesome-opencode community snapshot
• scripts/build-awesome-catalog.mjs — regenerates the community snapshot
• src/npm.ts — npm registry checks with a 30-minute cache
• src/paths.ts — config discovery, JSONC parsing, state I/O

State file: ~/.local/share/opencode/ecosystem-manager/state.json

The official catalog is maintained by hand. The community catalog is a snapshot; refresh it when the upstream list or package metadata changes:

npm run refresh:catalog

Development

npm install
npm run typecheck
npm run pack:dry
npm run refresh:catalog   # requires network access to GitHub and npm

To load the checkout without publishing, point OpenCode at the directory:

{
  "plugins": ["/absolute/path/to/OpencodeDesktopPluginManager"]
}

License

MIT