Goose

Make Goose follow an instruction: instruction.md keeps a file current, and Goose reads it again with every message you send. 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 arriveswith every message
Set upwatch, and a setting
Checked againstGoose 1.60.1
SystemsAny; the commands below are for a POSIX shell

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

Goose takes no text from a hook, but reads the file named by GOOSE_MOIM_MESSAGE_FILE again with every message. instruction connect --host goose <uri> prints the commands and Goose's MCP settings:

Shell and ~/.config/goose/config.yaml
# Goose re-reads GOOSE_MOIM_MESSAGE_FILE with every message: instruction.md keeps .instruction/current.md current
npx -y instruction.md watch instruction://acme/support-agent@stable --out .instruction/current.md --url https://instruction.md/mcp &
export GOOSE_MOIM_MESSAGE_FILE="$PWD/.instruction/current.md"
# ~/.config/goose/config.yaml — the server through this CLI's stdio server
extensions:
  instruction-md:
    type: stdio
    cmd: npx
    args: ["-y","instruction.md","mcp","--follow","instruction://acme/support-agent@stable","--url","https://instruction.md/mcp"]
    enabled: true
# sign the bridge in once: npx -y instruction.md login

Start Goose from the same terminal, so it sees the variable. Use an absolute path, as $PWD gives.

What happens

With each message you send, Goose reads the file again and gives the model its current text. A new version reaches the next message after watch writes it.

The plugin instead

Goose loads instruction.md's plugin, instruction-md/ at github.com/instruction-md/plugins, as an Open Plugin. Its hook, npx -y @instruction.md/agents hook auto, keeps .instruction/current.md fresh at Goose's events and prints nothing, so no watch is needed. The project needs its .instruction/follow.json.

Caveats and what isn't verified

  • Goose reads at most 64 KB from the file.
  • watch takes a live-update place while it runs (see Plans and live updates).

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).
  • Unset GOOSE_MOIM_MESSAGE_FILE, and remove the instruction-md extension from ~/.config/goose/config.yaml.
  • 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