Plugin cache directory naming/path inconsistency: docs say `~/.cache/opencode/node_modules/`, actual is `~/.cache/opencode/packages/`

[woohahahaaa]

Summary

OpenCode uses ~/.cache/opencode/packages/ as the installation location for npm plugins, but:

1. The directory is named cache/, which by XDG Base Directory spec means "discardable, regenerable data" — semantically wrong for installed plugin code
2. The official docs still reference the OLD path ~/.cache/opencode/node_modules/, which doesn't exist on current installs

This naming/path inconsistency is confusing for users (hard to find where plugins are installed) and may also mask bugs in the plugin loader (some users report plugins being downloaded but not loaded — see cross-reference below).

Environment

• OpenCode version: 1.17.7
• OS: Windows 11 (but this is a cross-platform issue)
• Investigation source: error shekohex/opencode-pty#39

Steps to Verify

ls ~/.cache/opencode/
# Expected per docs (opencode.ai/docs/plugins/):
#   node_modules/   ← docs say this is where plugins go
# Actual:
#   bin/            ← OpenCode CLI
#   packages/       ← actual plugin install location
#   skills/         ← skills cache
#   models.json

ls ~/.cache/opencode/packages/
# oh-my-openagent@latest/
# opencode-pty@latest/        ← example: an npm plugin
# oh-my-openagent/             ← legacy dir (sometimes empty)
# bun.lock
# package.json
# package-lock.json
# package.json.bak-pre-pty    ← auto-backup before each plugin change

The node_modules/ directory referenced in the docs does not exist on a current install.

Issues With This Design

1. XDG semantic violation

Per the XDG Base Directory Specification:

$XDG_CACHE_HOME defines the base directory relative to which user-specific non-essential data files should be stored. If $XDG_CACHE_HOME is either not set or empty, a default equal to $HOME/.cache should be used.

The directory MUST be on a local file system and not shared with any other system... The lifetime of the directory must be similar to the lifetime of the application.

XDG reserves ~/.cache/ for non-essential, regenerable data. Installed plugin code is:

• Not regenerable (depends on which plugins the user explicitly chose to install)
• Not non-essential (the user wants the plugin to keep working)
• Not transient (users expect it to persist across restarts)

Cache-cleaning tools (rm -rf ~/.cache, systemd-tmpfiles, bleachbit, etc.) may delete this directory, silently breaking all npm plugins on next OpenCode launch.

A more XDG-compliant location would be ~/.local/share/opencode/plugins/ (or ~/.config/opencode/plugins/ for both local file plugins and npm plugins, unified).

2. Docs are out of sync

The Plugins docs say:

npm plugins are installed automatically using Bun at startup. Packages and their dependencies are cached in ~/.cache/opencode/node_modules/.

But the actual directory is ~/.cache/opencode/packages/. There is no node_modules/ directory under ~/.cache/opencode/ on current installs.

3. May be related to plugin loading bugs

See shekohex/opencode-pty#39 — a user (me) added opencode-pty to the plugin array, the package was downloaded correctly to ~/.cache/opencode/packages/opencode-pty@latest/node_modules/opencode-pty/ with all dependencies hoisted, but OpenCode silently does not register the plugin (no error, no warning, no entry in the TUI plugin list, /pty commands return "no matching command").

I suspect the cache restructuring (node_modules/ → packages/) was not 100% consistent across the loader code, and some code paths still expect the old layout. While I can't reproduce this for oh-my-openagent (which works fine in the same packages/ location), the docs/loader/cache relationship deserves a fresh audit.

Suggested Actions

1. Fix the docs to reference ~/.cache/opencode/packages/ (or whatever the actual location is)
2. Audit the plugin loader to confirm it consistently reads from the correct path
3. Consider moving plugin installs to ~/.local/share/opencode/plugins/ (XDG-compliant) — or at minimum, document clearly that ~/.cache/opencode/packages/ should NOT be cleaned by cache-cleaning tools, and provide a opencode plugin clean command for safe manual cleanup

Reproduction Case

The original opencode-pty bug is filed at shekohex/opencode-pty#39. The discovery of this docs/path inconsistency came from that investigation.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [Bug] Plugin loader fails due to inconsistent directory structure in ~/.cache/opencode/packages #23502: Same ~/.cache/opencode/packages/ vs node_modules/ path inconsistency in the plugin loader — covers the directory structure confusion and plugin loading failures caused by the same layout mismatch.
• [FEATURE]: centralize persistent state and document all config/cache paths #28600: Related feature request to centralize and document all config/cache paths, including the XDG compliance concern raised here.

If your issue is specifically about the docs being out of sync (referencing node_modules/ when the actual path is packages/), please consider whether #23502 already captures the underlying problem. If this is a distinct aspect (e.g. the XDG semantic violation or the doc correction specifically), feel free to clarify and keep this open.

[Golden417]

Windows 11, opencode 1.17.7. Confirmed reproduction with extra context after multiple failed workarounds.

Repro:

• Add any of these to the plugin array in ~/.config/opencode/opencode.json: opencode-handoff, opencode-supabase, opencode-agent-memory, opencode-command-inject, opencode-ignore (all at @latest or pinned).
• Packages download correctly to ~/.cache/opencode/packages/<pkg>@<version>/node_modules/<pkg>/ with all deps hoisted.
• OpenCode silently does not register the plugin. No slash commands, no tool registrations, no UI feedback.
• Restarting makes no difference. No error appears in the log.

What works: Plugins that ship pre-compiled dist/index.js (e.g. @tarquinen/opencode-dcp, opencode-smart-title, cc-safety-net, opencode-chrome-devtools, opencode-with-claude, opencode-optimal-model-temps) all load and register correctly on the same setup.

Suspected distinguishing factor: Working plugins publish compiled JS in their npm tarball (files: ["dist/", ...]). Broken plugins publish raw TypeScript only (main: "src/plugin.ts").

Local file plugin workaround also fails: As per official docs, I placed entry files at ~/.config/opencode/plugins/<name>.ts that re-export the plugin from the source. The log shows init count=15 (local plugins discovered) but they still don't register. There are also bun install warnings: @opencode-ai/plugin: No matching version found for @opencode-ai/plugin@local originating from the per-project ~/.opencode/, project .opencode/, and <cwd>/.opencode/ directories. These auto-generated project dirs contain package.json with "@opencode-ai/plugin": "1.17.7".

Cache logs (e.g. for handoff): The loader resolves to packages/opencode-handoff@0.5.0/src/plugin.ts at the outer wrapper level rather than the nested node_modules/opencode-handoff/src/plugin.ts where the file actually exists. DCP's equivalent path also doesn't exist at the outer level but DCP still loads.

Cache directory contents (~/.cache/opencode/packages/opencode-handoff@0.5.0/):

• package.json ? {"dependencies": {"opencode-handoff": "0.5.0"}} (wrapper only, no main/exports)
• node_modules/opencode-handoff/package.json ? {"main": "src/plugin.ts", "files": ["src", "README.md"]} (real package)
• node_modules/opencode-handoff/src/plugin.ts exists with export const HandoffPlugin: Plugin = async (ctx) => {

Looks like the path resolution code in the loader uses the outer wrapper's node_modules/<pkg>/ for the dependency graph but uses the outer wrapper's directory for main resolution, which doesn't contain the entry file.