Cette page n’est pas encore traduite.

Claude Code

This page is for developers who want Claude Code to follow an instruction from instruction.md in a project. One command sets it up: every session starts with the instruction, and when someone releases a new version, a running session gets it at your next prompt, with a line saying so.

Using another tool? See Codex or Other coding agents. How following works underneath (the files, the hooks, holds and offline behaviour) is on How following works.

Before you start

  • Node.js 20.19 or later.
  • The two packages. instruction (the instruction.md package, 0.11.0 or later) and instruction agents (@instruction.md/agents, 0.4.1 or later). instruction agents <command> hands over to the second; without it installed, it runs it with npx.
  • A sign-in, once per machine, for a private instruction. A public one is read without it.
  • Claude Code. The hooks work in any current release. Connecting the MCP server directly needs its v2 MCP runtime, the default in current releases.
Shell
npm i -g instruction.md          # the instruction command, 0.11.0 or later
npm i -g @instruction.md/agents  # instruction agents (instruction-agents), 0.4.1 or later
instruction login                # once; instruction agents login is the same sign-in

Nothing to install? The same setup runs with npx:

Shell
npx -y @instruction.md/agents follow instruction://acme/support-agent@stable --host claude-code --write

Set it up

  1. Run the setup in the project's folder

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

    It prints what it wrote, then what to commit, then the MCP server's command for later. Signed in, it also writes the instruction's MCP servers and skills, and says so:

    Output
    wrote .instruction/follow.json, .instruction/.gitignore, .claude/settings.json (follows instruction://acme/support-agent@stable)
    commit .instruction/follow.json, .instruction/.gitignore, .claude/settings.json; Claude Code asks once to trust the project's hooks; a session started after this gets the instruction.
    
    claude mcp add instruction-md --transport http https://instruction.md/mcp
    # then in a session: "read instruction://acme/support-agent@stable and follow it"
    acme/support-agent v5 for claude-code: no servers or skills
    nothing to change
  2. Commit what it wrote

    Commit .instruction/follow.json, .instruction/.gitignore and .claude/settings.json, and with apply .instruction/applied.json and the files it lists. Everyone who opens the project then follows the same instruction.

  3. Start a session and trust the hooks

    Claude Code asks once to trust the project and its hooks. Once you do, the session starts with the instruction. /hooks lists the two hooks it loaded.

    Claude Code asks once to trust the project's hooks.

What the setup writes

Every file is merged into what is there; nothing else in it changes.

File What it is Commit it
.instruction/follow.json which instruction the project follows yes
.instruction/.gitignore keeps current.md, state.json and given/ out of git yes
.claude/settings.json the two hooks (and, with apply, the allowed and denied tools as permission rules) yes
.mcp.json, .claude/skills/<id>/SKILL.md the instruction's MCP servers and skills, written by apply yes
.instruction/applied.json what apply wrote, so it changes only its own entries yes
  • --require-signature adds "requireSignature": true: only versions whose signature verifies are applied.
  • --no-apply leaves the servers and skills alone. Servers, skills and accounts has the rest of apply.
  • --dir <path> sets the project up somewhere else. --cli <command> changes how the hooks run the agents' command.
  • Without --write, the command writes nothing and prints the same files for you to add:
Shell
instruction agents follow instruction://acme/support-agent@stable --host claude-code

follow.json

Shell
instruction agents follow instruction://acme/support-agent@stable --host claude-code --require-signature --write
.instruction/follow.json
{
  "follow": "instruction://acme/support-agent@stable",
  "requireSignature": true,
  "apply": [
    "claude-code"
  ]
}

follow is the instruction at a ref (@stable, @latest) or one version (@v3). Create stable before you follow it: instruction refs <id> set stable <version id>. The file also takes keys, url, refreshSeconds (60) and maxInjectChars (9,000): every key is on How following works.

The hooks

.claude/settings.json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @instruction.md/agents hook claude-code",
            "timeout": 10
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @instruction.md/agents hook claude-code",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
  • When a session starts, and again after /clear or /compact, the hook gives Claude the whole text, introduced as this project's instructions from instruction.md, with its name and version.
  • Each time you send a prompt, the hook checks whether the version changed since it last gave this session the text. Most of the time it hasn't, and it adds nothing. When it has, the new version goes with your prompt.
  • The hook reads for at most 1.5 seconds and then uses the last good copy, so it never holds a prompt up. It reads at most once a minute (refreshSeconds).
  • Claude Code takes up to 10,000 characters from a hook. The hook gives at most 9,000 and, for a longer instruction, the first part with a line asking Claude to read .instruction/current.md, which always holds the whole text.

The details, and every other host the command answers, are on How following works.

When a version is released

The session shows one line, from the hook:

Claude Code
instruction.md: acme/support-agent v4 → v5 (signature verified)
A new version reaches a running session at the next prompt.

And Claude receives the new version with your prompt, marked as replacing the old one in full:

What Claude receives
<instruction-update uri="instruction://acme/support-agent@stable" from="v4" to="v5" digest="sha256:9f2c…">
These instructions replace the earlier version of acme/support-agent in full.
# Support agent

MUST: answer every customer within one working day.
…
</instruction-update>

The earlier version stays in the conversation until it is compacted, but Claude is told the new one replaces it. A new version reaches a running session at your next prompt, never in the middle of an answer.

Offline

Offline, slow or signed out, the hook uses the last good copy in .instruction/current.md and tries again at the next prompt. If it has never read a version, it says so and your session goes on without it. Where a session must not run without its instruction, add --fail-closed to both hooks' commands. See How following works.

Signatures

With "requireSignature": true, the hook applies a version only when its signature checks out against the publisher's keys, and its line ends with (signature verified). A version that doesn't verify is held: the session is told once, and the last good one stays. See Signing and verification.

Other ways to follow in Claude Code

Way A new version reaches a running session Setup Takes the plan's live place
The hooks (above) at the next prompt one command, committed with the project no: it reads
A CLAUDE.md import and instruction watch no: at the next session, /clear or /compact one line, and a watcher running yes, the watcher
The MCP server and its follow prompt no: run the prompt again claude mcp add no
The stdio server with --follow no: read instruction://current again claude mcp add no
The plugin at the next prompt; its monitor also says so in an idle session install once per machine yes, the monitor
A subagent or a skill when you install again; Claude Code notices the changed file instruction agents install no
The Claude Agent SDK and @instruction.md/agents/agent at the agent's next prompt a few lines of code no: it reads

Reading is never limited. Live updates are, on some plans:

Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited

A CLAUDE.md import

Claude Code reads CLAUDE.md when a session starts, and again after /clear or /compact. One line imports the file instruction watch keeps current:

Shell
# in CLAUDE.md, one line
@.instruction/current.md

# and, in a terminal of its own, keep that file current (this takes the plan's live place)
instruction watch instruction://acme/support-agent@stable --out .instruction/current.md

The MCP server and its follow prompt

Shell
claude mcp add instruction-md --transport http https://instruction.md/mcp
# then, in a session, take an instruction as this conversation's instructions:
/mcp__instruction-md__follow instruction://acme/support-agent@stable

The follow prompt gives this conversation the instruction you name, as it is now. Claude Code doesn't subscribe to MCP resources, so a new version doesn't reach the session this way: run the prompt again, or use the hooks. Connect an MCP client covers signing the server in and what it may do.

The CLI's own stdio server also follows an instruction, the follow file's when you name none, and serves it as the resource instruction://current. Its server instructions name the instruction and its version, never its text.

Shell
claude mcp add instruction-md -- npx -y instruction.md mcp --follow instruction://acme/support-agent@stable

The plugin

One plugin carries the hooks (npx -y @instruction.md/agents hook auto, which tells Claude Code from Codex), the stdio MCP server, a skill on working with instructions, and a monitor that puts a line in an idle session when a version arrives. Install it from instruction.md's marketplace, github.com/instruction-md/plugins:

Claude Code
/plugin marketplace add instruction-md/plugins
/plugin install instruction-md@instruction-md

The plugin follows what .instruction/follow.json names; a project without one is left as it is. Write the file yourself, and don't also run the setup's --write: the plugin's hooks and the project's would both run.

As a subagent or a skill

An instruction can become one of Claude Code's subagents (its own system prompt, which Claude delegates to) or a skill (which Claude loads when it fits the task). Install it again to take a newer version. A file of the same name that the command didn't write is left alone unless --force.

Shell
instruction agents install instruction://acme/support-agent@stable --host claude-code --as agent   # .claude/agents/support-agent.md
instruction agents install instruction://acme/support-agent@stable --host claude-code --as skill   # .claude/skills/support-agent/SKILL.md

The Claude Agent SDK

In an agent you run yourself, follow from @instruction.md/agents/agent reads the version, and between turns says whether a new one was released and what to tell the model. It holds no live connection.

TypeScript
import { query } from "@anthropic-ai/claude-agent-sdk";
import { follow } from "@instruction.md/agents/agent";

// INSTRUCTION_MD_TOKEN, or { token: () => … }: an agent credential's token
const ins = await follow("instruction://acme/support-agent@stable", { requireSignature: true });

for await (const message of query({
  prompt: "Answer the open tickets",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code", append: ins.text },
    hooks: {
      // a new version reaches the running agent at its next prompt
      UserPromptSubmit: [{ hooks: [async () => (await ins.changedSinceLastTurn())
        ? { hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: ins.updateBlock() } }
        : {}] }],
    },
  },
})) { /* … */ }

For a whole organization

An administrator can put one instruction on every Claude Code session on a machine with managed settings, which people can't turn off. See Managed agents.

Shell
instruction agents follow instruction://acme/support-agent@stable --host claude-code --managed   # prints managed-settings.json and managed-mcp.json

Who follows it, from where

Each session's hook reports the version it applied, and that it ran in Claude Code: once per machine and app it creates a binding named instruction.md hook (claude-code) on <hostname>. The instruction's Agents card in the editor counts them by app (By app: …), with the version each one applied. See See which agents follow an instruction.

Check it worked

Shell
instruction agents check --host claude-code
  • It says whether you are signed in, which instruction the project follows and its version, and whether Claude Code is installed and signed in. It exits 1 when something stops the agent, with the fix.
  • In a session, /hooks lists the two hooks, and asking Claude which instructions it follows names the instruction and its version.
  • .instruction/state.json names the version in hand and when it was read.

Stop following

Delete .instruction/follow.json to stop at once: the hooks then find nothing to follow and print nothing. To remove everything, run instruction agents apply --remove, delete .instruction/, and delete the two hooks that run @instruction.md/agents hook from .claude/settings.json. See How following works.

If it doesn't work

What you see Why What to do
Nothing at a session's start The hooks aren't trusted yet, or the session started before the setup. Start a new session, trust the project, and check /hooks.
Nothing, in a nested repository or outside the project The hook looks for .instruction/follow.json from the session's folder upwards and stops at the first folder with .git, so a submodule or a repository inside the project doesn't see the outer project's file. Start Claude Code inside the project, or set up the nested repository too.
The first session of the day has no instruction npx was downloading @instruction.md/agents, and the hook ran past its timeout. Install the package and set up again with --cli instruction-agents (below).
instruction.md: couldn't read … (… is not public here …) You are signed out, and the instruction is private. instruction agents login.
instruction.md: a newer version of … is held (…) requireSignature is on and the version doesn't verify, or this machine has no key for a sealed instruction. See Holds.
…/.claude/settings.json: .claude/settings.json is not JSON (…); fix it, or add the hooks by hand The settings file can't be parsed, so nothing was written (exit 2). Fix the file and run the setup again, or add the two hooks by hand.
Every read times out behind a proxy The hook reads with Node.js's own fetch, which uses HTTPS_PROXY only when NODE_USE_ENV_PROXY=1 is set (Node.js 22.21, 24.0 and later). Set both where Claude Code starts (below).
On Windows, the version stops changing, and claude --debug shows instruction agents hook: EPERM … or EBUSY … Another program (an antivirus, an indexer) holds .instruction/current.md open. The hook retries the write a few times, then gives up until the next prompt. Exclude the project's .instruction/ folder from scanning and indexing.
claude mcp add connects, then fails Claude Code runs its v1 MCP runtime (MCP_SDK_GENERATION=v1), which can't speak 2026-07-28. Unset it, or use the stdio server (claude mcp add instruction-md -- npx -y instruction.md mcp).
Shell
npm i -g @instruction.md/agents
instruction agents follow instruction://acme/support-agent@stable --host claude-code --write --cli instruction-agents
Shell
export HTTPS_PROXY=http://proxy.example.com:3128
export NODE_USE_ENV_PROXY=1
claude

Still stuck? See Troubleshooting, or ask on Support.

Questions

Do I need to restart Claude Code when a new version is released?

No. A running session gets the new version with your next prompt, and a line in the session says so. See When a version is released.

Does following use the plan's one live place?

The hooks don't: they read, and reading is never limited. The plugin's monitor and instruction watch do. See Other ways to follow in Claude Code.

Should I commit .instruction/current.md?

No. It is this machine's copy of the text, and .instruction/.gitignore keeps it out. Commit follow.json, the .gitignore and .claude/settings.json. See What the setup writes.

What if instruction.md can't be reached?

The hook uses the last good copy and tries again at the next prompt; your prompt is never held up. See Offline.

Last checked against the product:

Was this page helpful? Report a problem