Zed, JetBrains and other ACP clients

Make any agent an editor runs over the Agent Client Protocol (ACP) follow an instruction: put instruction.md's go-between before the agent's command. 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 go-between before the agent
A new version arrivesat your next prompt
Set upthe agent's command
Checked againstACP schema v1.33.0
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

Zed, JetBrains IDEs and other editors run coding agents through the Agent Client Protocol (ACP). In the editor's settings for an agent, run this in place of the agent's own command, with that command after the --:

Shell
instruction agents acp -- <agent command…>

Or, without installing anything: npx -y @instruction.md/agents acp -- <agent command…>. The editor needs the full path of the command where it asks for one.

  • --follow <uri>: follow this instruction, not the .instruction/follow.json of the session's folder. --require-signature with it applies only versions whose signature checks out.
  • --url U: another instruction.md server.
  • --no-bridge: don't add instruction.md's MCP server to the session.

What happens

The command sits between the editor and the agent and passes every message through. A session starts with the instruction in its system prompt where the agent accepts one, or before your first prompt where it doesn't. After a release, the new version comes before your next prompt.

It also adds instruction-md, the instruction mcp stdio server, to the session's MCP servers. It reports the version a session applied, as ACP, and writes its notes to stderr, which ACP leaves for logs.

Zed's own agent has no hooks. It reads ~/.config/zed/AGENTS.md when a session starts, so keep that current for your own instructions:

Shell
instruction watch instruction://acme/support-agent@stable --out ~/.config/zed/AGENTS.md --block

Caveats and what isn't verified

  • Whether an agent takes a client's system prompt is its own: the go-between asks it when it starts (ACP's systemPrompt session capability).

Check it worked

Start a session in the editor and ask the agent which instructions it follows. The editor's log for the agent shows the go-between's notes.

Stop following

  • Put the agent's own command back in the editor's settings.

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