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(theinstruction.mdpackage, 0.11.0 or later) andinstruction agents(@instruction.md/agents, 0.4.1 or later).instruction agents <command>hands over to the second; without it installed, it runs it withnpx. - 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.
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:
npx -y @instruction.md/agents follow instruction://acme/support-agent@stable --host claude-code --write Set it up
Run the setup in the project's folder
Shellinstruction agents follow instruction://acme/support-agent@stable --host claude-code --writeIt 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:
Outputwrote .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 changeCommit what it wrote
Commit
.instruction/follow.json,.instruction/.gitignoreand.claude/settings.json, and with apply.instruction/applied.jsonand the files it lists. Everyone who opens the project then follows the same instruction.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.
/hookslists the two hooks it loaded.Screenshot coming soon Claude Code's first session in a project, asking to trust the project and its hooks, with the two instruction.md hooks listed.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-signatureadds"requireSignature": true: only versions whose signature verifies are applied.--no-applyleaves 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:
instruction agents follow instruction://acme/support-agent@stable --host claude-code follow.json
instruction agents follow instruction://acme/support-agent@stable --host claude-code --require-signature --write {
"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
{
"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
/clearor/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:
instruction.md: acme/support-agent v4 → v5 (signature verified) And Claude receives the new version with your prompt, marked as replacing the old one in full:
<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:
# 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
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.
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:
/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.
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.
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.
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
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,
/hookslists the two hooks, and asking Claude which instructions it follows names the instruction and its version. .instruction/state.jsonnames 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). |
npm i -g @instruction.md/agents
instruction agents follow instruction://acme/support-agent@stable --host claude-code --write --cli instruction-agents 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.