Cursor

Make a project follow an instruction in Cursor: one command writes its hooks, a rule every chat applies covers the start, and a new version arrives after the next tool call. The same setup for other tools, and how each one takes a new version, is on Other coding agents.

At a glance

How it followshooks, and a rule
A new version arrivesafter the next tool call
Set upone command, and watch
Checked againstCursor 2026.11.13, from its documentation
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

In your project's folder, signed in (instruction login), run:

Shell
instruction agents follow instruction://acme/support-agent@stable --host cursor --write

It writes, merged into what is already there:

  • .instruction/follow.json: the instruction the project follows. Commit it.
  • .instruction/.gitignore: keeps the fetched copy (current.md), state.json and given/ out of git.
  • .cursor/hooks.json: the hooks. Commit it.
.cursor/hooks.json
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "command": "npx -y @instruction.md/agents hook cursor --event sessionStart",
        "timeout": 10
      }
    ],
    "postToolUse": [
      {
        "command": "npx -y @instruction.md/agents hook cursor --event postToolUse",
        "timeout": 5
      }
    ],
    "preCompact": [
      {
        "command": "npx -y @instruction.md/agents hook cursor --event preCompact",
        "timeout": 5
      }
    ]
  }
}

Cursor runs a trusted workspace's hooks. Some Cursor builds drop a hook's context: also keep an always-applied rule — npx -y @instruction.md/agents watch --out .cursor/rules/instruction-md.mdc --rule (git-ignore it).

Keep the always-applied rule current with this, left running, and git-ignore the file:

Shell
instruction watch --out .cursor/rules/instruction-md.mdc --rule

Without an address, watch follows the project's .instruction/follow.json. --rule writes the instruction under a rule's front matter with alwaysApply: true, and replaces it at each version.

What happens

Cursor runs a trusted workspace's hooks. A session gets the instruction's whole text when it starts (sessionStart), and a new version after the next tool call (postToolUse). Before Cursor compacts a chat (preCompact), the hook forgets what it holds.

Some Cursor builds are reported to drop what a hook adds when a session starts. The rule is the path that doesn't depend on it.

The MCP server

Cursor speaks an earlier version of MCP than instruction.md's server, so its agent reaches it through the instruction command's stdio server, signed in once with instruction login. instruction connect --host cursor <uri> prints:

.cursor/mcp.json
{
  "mcpServers": {
    "instruction-md": {
      "command": "npx",
      "args": [
        "-y",
        "instruction.md",
        "mcp",
        "--follow",
        "instruction://acme/support-agent@stable",
        "--url",
        "https://instruction.md/mcp"
      ]
    }
  }
}

The plugin instead

instruction-md-cursor/ at github.com/instruction-md/plugins is the same in Cursor's plugin layout: the hooks, the MCP server, and an always-applied rule that points the agent at .instruction/current.md. It isn't in a marketplace yet, and how Cursor reads a plugin's hooks is not verified.

Caveats and what isn't verified

  • Not yet verified: additional_context reported not to reach the model in some builds (forum).
  • Cursor also runs a project's .claude/settings.json hooks. Where both are set up, a session still gets each version once.
  • watch takes a live-update place while it runs (see Plans and live updates).

Check it worked

Run the hook by hand, as the tool would at that event. It prints what the tool receives: the instruction's whole text the first time, and nothing when you run it again right away, because a session gets each version once.

Shell
echo '{}' | npx -y @instruction.md/agents hook cursor --event sessionStart --dir .

Then start a new session and ask which instructions it follows. Once a session has read it, .instruction/current.md holds the copy the hooks keep, and the instruction's Agents card counts the follower under this tool.

Stop following

  • Remove the entries that run @instruction.md/agents hook cursor from .cursor/hooks.json.
  • Stop watch and delete .cursor/rules/instruction-md.mdc.
  • Delete .instruction/follow.json, or the whole .instruction/ folder.

If it doesn't work

What you seeWhyWhat to do
Running the hook by hand prints nothingNo .instruction/follow.json in the folder or above it, up to the repository's root; or it gave this version moments agoRun the setup in the project's folder, or pass --dir. A version the session already has isn't given again: nothing is wrong
instruction.md: couldn't read …; this session goes on without itOffline, not signed in, or the address is wrong, and there is no copy yetinstruction login, then check the address in .instruction/follow.json
instruction.md: a newer version of … is held (…)The new version's signature doesn't check out, and the follow file asks for oneNothing to do on this machine: the session keeps the version it has. See How following works
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