OpenCode
Make a project follow an instruction in OpenCode: instruction.md keeps a file current, and OpenCode reads it again before every request to the model. The same setup for other tools, and how each one takes a new version, is on Other coding agents.
At a glance
| How it follows | a file it reads again |
|---|---|
| A new version arrives | before the next model request |
| Set up | watch, and its settings |
| Checked against | OpenCode 2.3.2 and 1.19.6, against their documentation and source |
| Systems | Wherever the tool and Node.js 20.19 or later run |
What you need: Node.js 20.19 or later, the instruction.md package
(npm i -g instruction.md, 0.11.0 or later) and @instruction.md/agents 0.4.1 or later, which
instruction agents … runs. Every instruction agents … command also runs, without installing
anything, as npx -y @instruction.md/agents …, and every instruction … command as
npx -y instruction.md ….
Set up
OpenCode reads the files listed under instructions again before every request to the model, and tells the model when one changed. So the instruction command keeps .instruction/current.md current, and OpenCode lists it. instruction connect --host opencode <uri> prints both:
// opencode.jsonc — OpenCode re-reads its instructions files before every model request and says when one changed;
// instruction.md keeps .instruction/current.md current (git-ignore it): npx -y instruction.md watch instruction://acme/support-agent@stable --out .instruction/current.md --url https://instruction.md/mcp
{
"instructions": [
".instruction/current.md"
],
"mcp": {
"servers": {
"instruction-md": {
"type": "remote",
"url": "https://instruction.md/mcp",
"protocol": "2026-07-28"
}
}
}
}
// OpenCode signs you in when the server asks
// OpenCode 1.x: the same "instructions"; the server through this CLI's stdio server:
// "mcp": { "instruction-md": { "type": "local", "command": ["npx","-y","instruction.md","mcp","--follow","instruction://acme/support-agent@stable","--url","https://instruction.md/mcp"] } } Leave the watch command running (git-ignore .instruction/current.md):
instruction watch instruction://acme/support-agent@stable --out .instruction/current.md --url https://instruction.md/mcp What happens
OpenCode 2 adds an instruction update before the next model request once the file changed, even in the middle of a task. OpenCode 1.x reads every listed file again for each model request.
OpenCode 2 connects to https://instruction.md/mcp itself, with "protocol": "2026-07-28", and signs you in when the server asks. OpenCode 1.x takes the same instructions entry and reaches the server through the instruction command's stdio server (the "type": "local" form above).
Caveats and what isn't verified
watchtakes a live-update place while it runs (see Plans and live updates).- A file kept by
watchholds the text a model receives. Listing an instruction's web address underinstructionsinstead gives OpenCode the authored text, with no signature check and no report.
Check it worked
Read the instruction once, as watch does, and write it:
instruction watch instruction://acme/support-agent@stable --out .instruction/current.md --once It prints applied v… and the file it wrote, and exits 0; 6 means nothing could be applied. Then start the tool and ask which instructions it follows.
Stop following
- Stop
instruction watch(Ctrl-C, or the service you made for it). - Remove
.instruction/current.mdand theinstruction-mdserver fromopencode.jsonc. - Delete
.instruction/current.md.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
| A new version doesn't reach the tool | instruction watch isn't running, so the file keeps the version it last wrote | Start it again, or run it as a service (Keep watch running) |
live updates are taken: … Still reading on schedule. | Another agent or app has your plan's live updates | Nothing breaks: watch reads every 60 seconds (Plans and live updates) |
| A private instruction isn't read | The command isn't signed in | instruction login (--device on a machine without a browser) |
| Still stuck | Ask us |
Related
- Other coding agents: every tool at a glance
- How following works: the follow file, the hooks, offline behaviour
- Kilo Code
- Goose
- Aider
- Live updates