pi

Make pi follow an instruction: instruction.md's extension puts it in a section of pi's system prompt, and a new version replaces that section at your next prompt. The same setup for other tools, and how each one takes a new version, is on Other coding agents.

At a glance

How it followsits own package
A new version arrivesat your next prompt, in its system prompt
Set uppi install
Checked againstpi 1.5.2
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

Shell
pi install npm:@instruction.md/agents

This installs instruction.md's extension for pi. pi -e npm:@instruction.md/agents loads it for one run only.

The extension reads the project's .instruction/follow.json. Write it yourself, and commit it:

.instruction/follow.json
{
  "follow": "instruction://acme/support-agent@stable"
}

To follow one instruction in every project that has no such file, set INSTRUCTION_MD_FOLLOW to its address.

What happens

Before every run, the extension puts the instruction into a section of pi's own system prompt, named instruction. When a new version is out, pi replaces only that section. So the new version reaches a running session at your next prompt, as part of its system prompt, and pi shows you a line saying so.

It reads the way the hooks do: at most every refreshSeconds, within 1.5 seconds, else the last good copy. It checks signatures when the follow file asks, and reports the version a session applied, as pi.

Caveats and what isn't verified

  • Signed out, the extension reads public instructions only. Sign in with instruction login.

Check it worked

Start pi in the project and ask which instructions it follows. The instruction's Agents card counts the follower under pi.

Stop following

  • Remove npm:@instruction.md/agents from pi's packages.
  • Delete .instruction/follow.json if nothing else uses it.

If it doesn't work

What you seeWhyWhat to do
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