Getting OpenCode plugins working in your organisation

If your organisation is rolling out OpenCode and the plugin system isn’t behaving, ie. plugins stuck on stale versions, private registry installs failing, or Desktop not picking up what CLI already installed, this covers the why, and a nice workaround I found.

What’s exactly wrong?

At my current job, we have different factions forming for people using different coding harnesses. Some on Claude Code, some on Codex, but more recently I’ve seen a sense internally, as well as more broadly in the industry, the move to a more agnostic coding harness, in order for the business to be able to follow the most cost effective and performant AI providers at any given point in time.

OpenCode stood out as one that people had appreciated working with in their personal time. The harness is actually fairly amazing, save for a few performance quirks when landing in a directory with lots of files.

OpenCode even has thought through the concept of configuration precedence order, has a .well-known/opencode endpoint, showing off some of the thought and care that went into the design of the project.

One of the things that compelled companies to OpenCode was the ability to configure custom internal gateways for their workforce’s LLMs. The main method of providing these to your users seems to be through the plugin system to allow for customisation of the harness, settings, controls, and more importantly, internal providers.

All a user has to do is run

npm i -g opencode-ai
opencode plugin "@my-org/custom-plugin@^1.2.3"

However, there’s a few things that we ran up against that made life a little challenging relating to this. You can of-course skip ahead to get the fixes below ⬇️ if you’ve already faced some of these problems.

On plugins, `@latest` is as “latest” as you’re going to get.

https://github.com/anomalyco/opencode/issues/25293

“How do we get the latest OpenCode CLI versions to users, without going to IT to update MDM every time we want an update to roll out new plugin update?”

When you define:

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

You’ll be stuck on whatever version lands on that user’s machine for until you clear all user cache and reinstall OpenCode.

This is because (I believe) that enough bugs were starting to be launched around the heterogeneity of people’s NPM setups (think bun|pnpm|deno|npm * all versions * win|mac|linux ≈ a tonne of combinations) that because of this, in #18308, OpenCode made the decision to move from BunProc to Arborist (the in-built OpenCode npm package manager) in order to avoid these problems. This will install plugin to a custom location ~/.cache/opencode/node_modules/ where OpenCode will look after them for you.

However, I don’t think enough work has gone into ensuring that plugins get sufficient attention: updating, post-install scripts, etc. There is a few people trying to submit PRs to this with mixed success.

Supporting Private Registries

One other element that came as a result of OpenCode moving to Arborist, it also means that they will have to pick up on every user’s ~/.npmrc file (and derivatives) in order to respect private registry settings, that come into play at larger organisations that block access to the public npm registry.

This one actually got fixed for the 90% back in April.

#21697
#22025
#22765
.npmrc support #24001 🎉

But still have some ways to go to support other paths.

OpenCode plugins sometimes don’t get recognized on OpenCode Desktop

After OpenCode Desktop was migrated from Tauri to Electron around v1.14.39 (May 2026), a cluster of issues started cropping up. The Electron sidecar introduced a @opencode-ai/plugin@local peer dep that fails to resolve, plugin-registered agents stopped appearing in the agent picker, and the Desktop app started hanging or crashing on startup. Most of the fix PRs for this are still sitting unmerged.

#26085 Electron sidecar: npm plugins fail, peer dep resolves as @local
#30525 Desktop agent picker doesn’t show plugin-registered agents
#31708 Desktop hangs on Windows 11, npm install failed
#29516 fix: add shell polyfill for desktop plugin support
#30532 fix(desktop): plugin agents missing from agent picker

Side-loading in OpenCode

I think we found a nice fix for all three of these.

Below is a generic template for you to use to side-load your own plugins into OpenCode CLI & Desktop.

npm i @org/plugin ships a postinstall.js that copies a loader.js into ~/.config/opencode/plugins/, a directory OpenCode auto-discovers on startup, separate from the Arborist-managed ~/.cache/ path. On load, the loader calls out to pnpm/npm/bun to locate where the package actually lives in the system’s global store, then imports it from there. The plugin ends up utilising the user’s system package manager rather than OpenCode’s, so normal pnpm update -g or npm update -g flows will update the plugin as expected, private registry config is respected, and Desktop picks it up the same way CLI does.

index.ts is where you add your own providers, MCP servers, auth flows, whatever your org needs to push down to users.

“why don’t you contribute back?”

That’s an excellent observation, and you’re right to push back…

Honestly, this template is partly a proof of concept that OpenCode should just offer this as a first-class option: let plugins live outside Arborist, in whatever package manager the user already has. It would sidestep a lot of the ecosystem headaches without requiring a core rewrite.

Modifying the ‘arborist’ implementation directly is not something I think is particularly welcome from an outside contributor. It’s a core part of the CLI app, and even reverting to “use the system npm” would be a breaking change for anyone who’s adopted the current behaviour. The PRs people have submitted to this area have had mixed success at best, and most are sitting open.