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 followsa file it reads again
A new version arrivesbefore the next model request
Set upwatch, and its settings
Checked againstOpenCode 2.3.2 and 1.19.6, against their documentation and source
SystemsWherever 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.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):

Shell
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

  • watch takes a live-update place while it runs (see Plans and live updates).
  • A file kept by watch holds the text a model receives. Listing an instruction's web address under instructions instead 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:

Shell
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.md and the instruction-md server from opencode.jsonc.
  • Delete .instruction/current.md.

If it doesn't work

What you seeWhyWhat to do
A new version doesn't reach the toolinstruction watch isn't running, so the file keeps the version it last wroteStart 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 updatesNothing breaks: watch reads every 60 seconds (Plans and live updates)
A private instruction isn't readThe command isn't signed ininstruction login (--device on a machine without a browser)
Still stuckAsk us

Last checked against the product:

Was this page helpful? Report a problem