On DSH: the
odf-gatesentry must only inject services the profile provides — injecting a missing service pends the entire plugin at boot (one stderr line, then silence).df install-dshhandles this per profile. Details:dsh.md.
Each project must register the plugin exactly once. Plugin arrays
merge across config files (global opencode.jsonc, project
./opencode.jsonc, ./.opencode/opencode.json[c]), so a second entry in
another file — even one pointing at a different path of the same repo such
as dist/ — loads the same plugin ID twice and the duplicate fails. Check
all three locations, and verify with:
opencode api get "/api/plugin?location[directory]=/path/to/project"(The server log only shows harmless loading plugin lines for both
entries — the API view is the one that tells the truth.)
Point the entry at the repository root, not at dist/ directly: a bare
directory without package.json/exports resolves only the server part.
One root entry loads every part (server via dist/adapters/opencode/index.js, TUI via
tui.tsx, resolved through the exports map).
OpenCode caches downloaded plugins in
~/.cache/opencode/packages/opencode-dev-framework*/. If you previously
loaded a published version and then switch to a local source, clear that
cache so OpenCode does not reuse the old build:
rm -rf ~/.cache/opencode/packages/opencode-dev-framework*After every source change, rebuild — OpenCode loads the compiled dist/
output:
npm run buildPlugin code runs in the shared opencode serve backend, not in your
terminal/TUI process — restarting the client alone reuses the old server,
so a rebuilt dist/ sits unread and new behavior silently never fires.
After every plugin upgrade or rebuild, restart the serve backend so new
and continued sessions pick up the new code.
Requires OpenCode v2.x (@opencode/plugin ^2) — tested on v2.0.26
and v2.2.0. On v1.18.18–1.18.31 use the v1 branch of this plugin
(plugin key). The ./tui companion (/df-status and /df-help modals)
is auto-discovered from the npm entry on v2 — no separate tui.json
needed.
Under standard/strict, a red tree at the idle boundary continues the
session until the cause is fixed — even if you asked for a report-only
diagnosis (see Blocked gate, fix,
pass). That is the documented price of a
blocking profile, not a bug. Your options:
- Call
dev_framework_verifydirectly mid-turn for the report, then close the session yourself — the verdict is pure report, but the continuation still fires if you let the turn go idle on the red tree. - Drop to
advisoryfor the session (/df-profile advisory) and flip back after — the gate reports instead of blocking. This is the only true look-without-touching. - Do nothing: if the failure is identical with no new edits across three
evaluations, the gate stands down early on zero progress instead of
spending the rest of
gate.max_blocks. Bounded either way, but the early stop saves the wasted continuations.
Lint steps skip tracked files that no longer exist — a missing file can never fail the gate. But a deletion is still a real change: typecheck and test steps run, because removing a file can break its dependents, and the clean pass is cached so the gate does not re-run it every idle. If your gate ever cites a file you already deleted, update the plugin — that was a bug in older versions, not your tree.
Every gate evaluation is logged as JSON lines: OPENCODE_DEV_FRAMEWORK_LOG_FILE
overrides the location, otherwise the default is
~/.local/share/opencode-dev-framework/opencode-dev-framework.log
($XDG_DATA_HOME when set; ~/Library/Logs on macOS;
%LOCALAPPDATA% on Windows). Grep it for verdicts:
grep -o '"reason":"[a-z]*"' ~/.local/share/opencode-dev-framework/opencode-dev-framework.log \
| sort | uniq -cThe file rotates at 5 MB with one backup (.log.1), so worst case
is 10 MB — history depth is thousands of evaluations.
Run a private server with the plugin trace on and read the log:
OPENCODE_DEV_FRAMEWORK_LOG_FILE=/tmp/odf.log opencode run --standalone --print-logsOPENCODE_DEV_FRAMEWORK_LOG_LEVEL (default debug) sets the minimum
level that reaches stderr and the file — raise it to warn to silence
routine info/debug lines. Unknown values fall back to debug.
Plugin code runs in the opencode serve backend, not in your terminal
process — a variable exported only in the TUI shell never reaches it.