Getting OpenCode plugins working in your organisation

OpenCode, an open-source coding agent, faces plugin management issues in enterprise deployments, including stale versions and private registry failures. A workaround involves using exact version pinning and configuring npm registry settings in the OpenCode config file. The problems stem from OpenCode's shift to Arborist for plugin installation, which lacks robust update mechanisms.

Getting OpenCode plugins working in your organisation 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 https://www.linkedin.com/posts/stefan-avram-62696713a apple-demonstrated-opencode-at-wwdc26-at-activity-7470529946789064704-e3PQ/ in the industry https://blog.cloudflare.com/ai-code-review/ :~:text=Instead%20of%20building%20a%20monolithic%20code%20review%20agent%20from%20scratch%2C%20we%20decided%20to%20build%20a%20CI%2Dnative%20orchestration%20system%20around%20OpenCode%2C%20an%20open%2Dsource%20coding%20agent%2E , 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 https://opencode.ai/ stood out as one that people had appreciated working with in their personal time. The harness is actually fairly amazing, save for a few https://github.com/anomalyco/opencode/issues/32511 performance https://github.com/anomalyco/opencode/issues/20695 quirks https://github.com/anomalyco/opencode/issues/28680 when landing in a directory with lots of files. OpenCode even has thought through the concept of configuration precedence order https://opencode.ai/docs/config/ precedence-order , has a .well-known/opencode endpoint https://opencode.ai/docs/config/ remote , 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 https://opencode.ai/docs/plugins/ 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 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 https://github.com/anomalyco/opencode/pull/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 https://docs.npmjs.com/cli/v8/configuring-npm/npmrc files 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% https://github.com/anomalyco/opencode/pull/24001/changes back in April. But still have some ways to go to support other paths. https://github.com/anomalyco/opencode/issues/21324 issuecomment-4423091707 OpenCode plugins sometimes don’t get recognized on OpenCode Desktop After OpenCode Desktop was migrated from Tauri to Electron https://github.com/anomalyco/opencode/pull/25822 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 https://github.com/anomalyco/opencode/issues/26085 Electron sidecar: npm plugins fail, peer dep resolves as @local - 30525 https://github.com/anomalyco/opencode/issues/30525 Desktop agent picker doesn’t show plugin-registered agents - 31708 https://github.com/anomalyco/opencode/issues/31708 Desktop hangs on Windows 11, npm install failed - 29516 https://github.com/anomalyco/opencode/pull/29516 fix: add shell polyfill for desktop plugin support - 30532 https://github.com/anomalyco/opencode/pull/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 https://github.com/sifex/opencode-plugin-template/blob/main/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 https://www.npmjs.com/package/@npmcli/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 https://anoma.ly/ 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 https://anoma.ly/ :~:text=We%20are,others 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.