Skip to content

Commit 445b1ee

Browse files
gundisalwaclaude
andcommitted
research-0013: add opencode's static instructions-field mechanism (source-verified)
Maintainer flagged a separate, non-plugin mechanism in OpenCode: opencode.json's "instructions" array (project or global ~/.config/opencode/opencode.json). Verified against actual source (packages/opencode/src/session/instruction.ts), not just docs, after two doc-page fetches disagreed on remote-URL support — source settles it: yes, genuine http(s):// URLs are fetched live (5s timeout), alongside local paths/globs, all merged with AGENTS.md automatically. This is a third delivery shape, distinct from both models named earlier: static harness-native config pointing at always-load content, with the harness doing the fetch — no vendoring, no hook/plugin machinery. Set at the global-config layer it needs zero per-project commits at all, which fits the single-user scope note even more directly than a hook would. Also notes a real (now-closed) reliability bug on this exact field (anomalyco/opencode#4758), and flags that this note's Claude Code side rests on docs only, not source — same discrepancy risk the OpenCode doc-pages just demonstrated, named as an open question rather than assumed equally solid. Still draft, no gate run. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01H4vX9nnWUdUkAJjdjCuWbR
1 parent 10ae7d2 commit 445b1ee

1 file changed

Lines changed: 69 additions & 6 deletions

File tree

‎research/0013-plugin-native-content-without-vendoring.md‎

Lines changed: 69 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,47 @@ assuming Claude Code's `SessionStart`/`additionalContext` shape generalizes:
140140
it can deliver model 2's actual goal (always-on, zero-vendor instructions) — that
141141
needs checking per harness, not assumed from "has a plugin system."
142142

143+
**Correction/addition (2026-07-21) — OpenCode has a separate, non-plugin mechanism that
144+
does deliver the goal.** The maintainer flagged this directly: OpenCode's config
145+
(`opencode.json`/`opencode.jsonc`, project *or* global `~/.config/opencode/opencode.json`)
146+
has an `instructions` field — a static array, not a hook, not part of the plugin system.
147+
Verified against the actual resolution code
148+
(`packages/opencode/src/session/instruction.ts`, `anomalyco/opencode`, fetched 2026-07-21),
149+
not just the docs page (which two independent fetches gave inconsistent answers on — see
150+
below):
151+
152+
```js
153+
const urls = (config.instructions ?? []).filter(
154+
(item) => item.startsWith("https://") || item.startsWith("http://"),
155+
)
156+
```
157+
158+
`instructions` accepts local paths, glob patterns (`packages/*/AGENTS.md`), and — per
159+
this source, not just the docs — genuine **remote `http(s)://` URLs**, fetched live with
160+
a 5-second timeout, all combined automatically with `AGENTS.md`. Set in the *global*
161+
config, this needs zero per-project file commits at all: a single line, once, per user —
162+
which fits the current single-user reality (Scope section above) even better than a
163+
hook would. One reliability caveat found in the same search: a real bug report
164+
(`anomalyco/opencode#4758`, "custom instruction files in `opencode.jsonc` not being
165+
loaded") describes exactly this field silently not firing — closed as completed
166+
2026-03-26, so presumed fixed, but it shows the field has had at least one real rough
167+
edge, not a purely theoretical mechanism.
168+
169+
This doesn't fit cleanly into either of the two models above — it's neither vendored
170+
copy nor plugin-hook delivery, but a third shape: **static, harness-native config
171+
declaring where to always-load instructions from, with the harness itself doing the
172+
fetch.** Worth naming as its own category rather than stretching "model 2" to cover it.
173+
It's also a useful asymmetry to note against Claude Code directly: Claude Code has the
174+
*hook* mechanism OpenCode's plugin system lacks, but OpenCode's `instructions` field can
175+
do something Claude Code's own `@import` cannot — fetch a remote URL live. Neither
176+
harness's native mechanism is a strict superset of the other's.
177+
178+
*(Methodological note: the two doc-page fetches earlier in this survey disagreed on
179+
remote-URL support — one said yes, one said no. Source code, not docs, settled it. Kept
180+
here as a reminder that this survey's doc-only findings — including the Claude Code
181+
`SessionStart`/`additionalContext` finding above — are one level less certain than this
182+
OpenCode finding, which is source-verified.)*
183+
143184
This is the shape a fuller survey would take: for each harness in `research-0010`'s
144185
registry (once the landing-page effort makes that registry relevant again), check not
145186
just "does it have a plugin system" but specifically "can a plugin inject persistent,
@@ -205,12 +246,26 @@ same-session extension of the current line of work.
205246
that the gap is real today, not hypothetical. Note this gap is specific to *model 2*
206247
(plugin-native) — model 1 (vendored) has no such gap, which is part of why model 1
207248
stays as the fallback rather than being retired.
208-
- **Which other harnesses' native plugin systems support always-on instruction
209-
injection?** Surveyed so far: Claude Code — yes (`SessionStart` + `additionalContext`);
210-
OpenCode — no (hook surface is tool/session/file/message-scoped only). The rest of
211-
`research-0010`'s registry (Codex, Copilot, Gemini CLI, Cline, Devin/Cascade, Windsurf,
212-
Cursor, Continue.dev, Aider) is unsurveyed for this specific capability — deferred
213-
until multi-harness support is active again (see Scope section above).
249+
- **Which other harnesses' native mechanisms support always-on instruction delivery
250+
without vendoring?** Surveyed so far: Claude Code — yes, via plugin + `SessionStart`
251+
hook (doc-sourced, not source-verified); OpenCode — its plugin system, no; its
252+
`instructions` config field, yes, including remote-URL fetch (source-verified). The
253+
rest of `research-0010`'s registry (Codex, Copilot, Gemini CLI, Cline, Devin/Cascade,
254+
Windsurf, Cursor, Continue.dev, Aider) is unsurveyed — deferred until multi-harness
255+
support is active again (see Scope section above). Worth checking each harness for
256+
*both* shapes found so far (hook-based and static-config-with-remote-fetch), not just
257+
one.
258+
- **Does Claude Code have an OpenCode-`instructions`-equivalent this survey missed** —
259+
a static config field with native remote-URL fetch, checked against source rather than
260+
docs? The doc-vs-source discrepancy found for OpenCode is reason enough to re-verify
261+
the Claude Code `@import`/`${CLAUDE_PLUGIN_ROOT}` finding (`anthropics/claude-code#9354`)
262+
against source before this note's Claude Code side is treated as equally solid as its
263+
OpenCode side.
264+
- **Is OpenCode's `instructions` field (global-config form) actually the better near-term
265+
fit** given the current single-user reality — one config line, no per-project
266+
vendoring, no hook/plugin machinery at all — worth prototyping before any Claude-Code-
267+
specific hook work, if OpenCode ever becomes a harness trellis targets. Not decided
268+
here; the maintainer's near-term focus is stated as Claude Code only (Scope section).
214269
215270
## Sources & confidence
216271
@@ -225,3 +280,11 @@ same-session extension of the current line of work.
225280
- OpenCode plugin system (npm/Bun distribution, hook surface) — **High** (official docs,
226281
`opencode.ai/docs/plugins/`, fetched directly 2026-07-21; corroborates the maintainer's
227282
own recollection rather than resting on it alone).
283+
- OpenCode `instructions` config field, including remote-URL fetch — **High**, source-
284+
verified (`packages/opencode/src/session/instruction.ts`,
285+
`anomalyco/opencode@dev`, fetched 2026-07-21) after two doc-page fetches
286+
(`opencode.ai/docs/rules/` vs `opencode.ai/docs/config/`) gave contradictory answers on
287+
remote-URL support — source settled it in favor of "yes."
288+
- `anomalyco/opencode#4758` (`instructions` field silently not loading) — **High**
289+
(GitHub issue, confirmed closed/completed 2026-03-26 via `gh issue view`) — a real,
290+
now-apparently-fixed reliability caveat on the mechanism above, not a live blocker.

0 commit comments

Comments
 (0)