Trials with updates, desktop apps, and private gateways
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.
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.
#26085Electron sidecar: npm plugins fail, peer dep resolves as@local
#30525Desktop agent picker doesn’t show plugin-registered agents - #31708Desktop hangs on Windows 11, npm install failed - #29516fix: add shell polyfill for desktop plugin support - #30532fix(desktop): plugin agents missing from agent picker
Side- 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 .js
into ~/.config/opencode/plugins/
, a directory OpenCode auto-discovers on startup, separate from the Arborist-managed ~/.cache/
path. On load, the 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.
The team at Anomaly have built something that’s (from what I’ve observed) been adopted by almost every major tech company in the world, and they’re currently getting inundated with thousands of issues, PRs, and feature requests. With what I assume to be a large investment behind them, it would be good to see some of these get addressed, especially as the plugin ecosystem becomes a bigger part of how organisations actually deploy this harness.