Цю сторінку ще не перекладено.

How following works

A follower keeps an agent on the version of an instruction its people chose: it reads the version a ref points at, applies it, and keeps the last good one when it can't read or verify a newer one. This page explains how the hooks, the follow file and the followers do that, so you can set a project up, debug it, and know what it does when the network is gone.

What a hook does at a session's start and at each prompt.

Who follows

Everything that follows an instruction uses the same rules, from the same code:

Follower Where How it gets a new version
The hooks (instruction agents hook <host>) Claude Code, Codex and 12 other coding agents it reads at a session's start and at the next prompt
The stdio server (instruction mcp --follow) any MCP host it reads when asked (instruction://current, the prompt follow)
instruction watch a terminal, a plugin's monitor live updates, then a read
The SDK followers and @instruction.md/agents/agent your own code live updates (followers), or a read between turns (the helper)
agentd its daemon live updates and MCP Events

A project names what it follows in .instruction/follow.json. The setup for each host is on Claude Code, Codex and Other coding agents.

Refs and versions

A follower follows one address. At a ref (@stable, @latest, any ref you made) it gets whatever version the ref points at now, so moving the ref is how a release reaches agents. At one version (@v3, @ver_…) it never changes. stable is never created for you: create it with instruction refs <id> set stable <version id> before anything follows @stable. Refs, their gates and promotion are on The model.

A ref never points at a revoked version. A follower pinned to a version that is later revoked holds it: see Holds.

Keep the last good version

A follower never replaces a working version with nothing. When a read fails, takes too long or brings a version the follower may not apply, the version it already has stays in force. Being unable to reach instruction.md means no updates, never no instructions.

Keep the last good version: no updates, never no instructions.

For the hooks the last good version is .instruction/current.md. It holds the delivered text (what a model receives: the instruction with its includes resolved and its parameters at their defaults, never the authored source with its front matter), written whole or not at all. A current.md edited by hand no longer matches the digest state.json recorded, so the hook treats it as missing and reads again.

Holds

A follower holds a new version, applies nothing and keeps the last good one, when:

  • the version was revoked (a pinned read);
  • it is sealed and this machine has no key for it, or the key hasn't been given the workspace's key yet;
  • signed out, the instruction isn't public (the HTTP read answers 404);
  • with requireSignature on: the version is unsigned, its signature doesn't verify against the publisher's keys, it was signed with a revoked key, or there are no publisher keys to verify it with.

The hook says so once per session and version: instruction.md: a newer version of acme/support-agent is held (…); keeping v4. A read that fails or runs past the deadline (offline, a refused token) is not a hold, but it ends the same way: the last good version stays, and the hook says at a session's start that it is using it. The lines it shows are listed under Hooks.

follow.json

.instruction/follow.json says what the project follows. Commit it, so everyone working on the project follows the same instruction. A follower looks for it in the agent's working directory and each directory above, stopping at the repository's root (a directory with .git).

instruction agents follow <uri> --host <host> writes only follow, requireSignature (with --require-signature), url (when the server isn't https://instruction.md/mcp) and, with --write for Claude Code or Codex, apply. Everything else in the file is kept. This is what --host claude-code --require-signature --write writes:

.instruction/follow.json
{
  "follow": "instruction://acme/support-agent@stable",
  "requireSignature": true,
  "apply": [
    "claude-code"
  ]
}

Every key it takes:

Key Type Default What it does
follow string, required The instruction: instruction://owner/name[@ref], instruction://ins_…@ref, or owner/name[@ref].
requireSignature boolean false Apply only versions whose author signature verifies. See Signatures.
keys string A JSON file of the publisher's keys ({"keys": […]} or […]), relative to the project. Without it, keys are discovered from the registry when signed in.
url string https://instruction.md/mcp The MCP server. INSTRUCTION_MD_URL or a hook's --url also set it; --url wins, then this, then the variable.
refreshSeconds number 60 How old current.md may be before a hook reads again. Younger, and the hook uses it without asking.
maxInjectChars number 9000 The most a hook puts into the conversation at once. A longer text is cut, with a line to read current.md.
apply true or a list of "claude-code", "codex" none Write the instruction's MCP servers and skills into these apps' files when a version changes them. true means ["claude-code"].
deploymentId string Written by the runner: the deployment this folder's agent is. Messages people write to it reach it at its next prompt.
converse boolean Written by the runner when it hosts the agent itself and hands messages over, not the hook.
.instruction/follow.json, every key (JSONC)
{
  // the one instruction: instruction://owner/name[@ref|@vN], instruction://ins_…@ref, or owner/name[@ref]
  "follow": "instruction://acme/support-agent@stable",
  // apply only versions whose author signature verifies; others are held and the last good text stays
  "requireSignature": true,
  // the publisher's keys, relative to the project ({ "keys": [...] } or [...]); else discovered (signed in only)
  "keys": ".instruction/acme-keys.json",
  // another MCP server (default https://instruction.md/mcp, or INSTRUCTION_MD_URL)
  "url": "https://instruction.example.com/mcp",
  // how old current.md may be before a hook reads again, in seconds (default 60)
  "refreshSeconds": 60,
  // the most a hook puts into the conversation at once, in characters (default 9000)
  "maxInjectChars": 9000,
  // write the instruction's servers and skills into these apps' files (true means ["claude-code"])
  "apply": ["claude-code", "codex"],
  // written by the runner (instruction agents run): the deployment this folder's agent is
  "deploymentId": "dep_…",
  // written by the runner: it hands messages to the agent itself, not the hook
  "converse": false
}

A file that isn't JSON, names no instruction or has a key of the wrong type is said once, at a session's start (instruction.md: … is not JSON: …), and nothing is given.

Other files

The project
.instruction/
  follow.json      committed: what the project follows
  .gitignore       committed: keeps the three below out of git
  current.md       the delivered text of the version in hand
  state.json       what current.md is, and what each session was given
  given/           one marker per session and version given
  applied.json     committed: the servers and skills apply wrote (with apply)
.claude/
  settings.json    committed: the two hooks
  • current.md, state.json and given/ are the machine's own. .instruction/.gitignore keeps them out of git, and the CLI adds the three lines whenever it writes there, keeping lines already in the file.
  • state.json says what current.md is (address, version, digest, whether its signature was verified, when it was read) and, for each agent session, the digest that session was given and the version reported for it. It keeps the last 50 sessions, none older than 14 days.
  • given/ holds one empty marker per session and version given. When two hooks fire for one event (an app that also runs Claude Code's hooks), the first to create the marker gives the text and the other skips. Markers older than 14 days are removed.
  • applied.json records the servers and skills instruction agents apply wrote, so a later apply changes and removes only its own entries. Commit it with the files it lists.
  • applied-note is a one-line note a background apply leaves for the hook to say at the next event, then deletes. Don't commit it.
.instruction/.gitignore
current.md
state.json
given/
.instruction/state.json (shortened)
{
  "uri": "instruction://acme/support-agent@stable",
  "label": "acme/support-agent",
  "canonical": "instruction://ins_01JD…@stable",
  "versionId": "ver_01JF…",
  "version": 5,
  "digest": "sha256:9f2c…",
  "authoredDigest": "sha256:41ab…",
  "signed": true,
  "verified": true,
  "fetchedAt": "2026-11-22T09:14:03.120Z",
  "sessions": {
    "5d1c…": { "digest": "sha256:9f2c…", "version": 5, "at": "2026-11-22T09:14:03.121Z", "givenAt": 1795338843121, "reported": "ver_01JF…" }
  }
}

A follow given by its address instead of a project (a managed hook's --follow <uri>) keeps its files in the user's cache, not in a project: $INSTRUCTION_MD_CACHE, else $XDG_CACHE_HOME/instruction-md, else ~/.cache/instruction-md, under follow/<hash of the address>/.

Hooks

A coding agent runs a hook command at its events, with the event as JSON on stdin, and reads one answer from stdout. The hook command is instruction agents hook <host>; the setup writes it as npx -y @instruction.md/agents hook claude-code. For Claude Code it is two hooks in .claude/settings.json:

.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
          }
        ]
      }
    ]
  }
}

What a session is given:

  • At a session's start (startup, resume, clear, compact; Codex also fork) the whole text, introduced as the project's instructions, with its name and version. After clear or compact the context was wiped, so the text is given again.
  • At each prompt nothing at all while the session has the current version: no words, no cost. When the version changed since this session was given it, the new version, marked as replacing the old one in full, and one line for the person.
  • A resumed session that holds another version is given the replacement; one that holds this version is given it whole again.
At a session's start
These are this project's instructions from instruction.md (acme/support-agent v4). Follow them.
<instruction uri="instruction://acme/support-agent@stable" version="v4" digest="sha256:41ab…">
# Support agent

MUST: answer every customer within one working day.
…
</instruction>
At the next prompt, after a release
<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 lines a person sees, one at a time:

The session
instruction.md: acme/support-agent v4 → v5 (signature verified)
instruction.md: acme/support-agent couldn't be read now (no answer within 1500 ms); using the last good copy, v4
instruction.md: a newer version of acme/support-agent is held (version ver_01JF… is unsigned); keeping v4
instruction.md: couldn't read acme/support-agent (nothing was read); this session goes on without it

Limits a hook works within:

  • The read. A hook reads for at most 1.5 seconds (--deadline <ms> changes it), then uses current.md. It reads at most once every refreshSeconds.
  • The report. When signed in, it reports the version a session applied, only if it has spent less than 1.2 seconds so far, and waits at most 0.6 seconds for the answer. A report missed is sent at a later prompt.
  • The size. Claude Code takes up to 10,000 characters from a hook; the hook gives at most maxInjectChars (9,000 by default). Codex cuts a hook's context at about 2,500 tokens unless the handler says otherwise, so its hooks carry "additionalContextLimit": 0. A text over the limit is given in part, ending:
A cut block
…

This is only the first part. The full text is in .instruction/current.md; read it now.
</instruction>
  • The host's timeout. The setup gives the start hook 10 seconds and the prompt hook 5. In Claude Code a UserPromptSubmit hook that times out blocks the prompt, which is why the hook keeps to its own deadline and always exits 0.
  • The first run. npx -y @instruction.md/agents downloads the package the first time it runs on a machine, which can take longer than the hook's timeout. That session starts without the instruction and the next one has it. To avoid it, install the package and name the installed command:
Shell
npm i -g @instruction.md/agents
instruction agents follow instruction://acme/support-agent@stable --host claude-code --write --cli instruction-agents
# the hooks then run: instruction-agents hook claude-code

The other hooks the command answers, with their files and events, are on Other coding agents.

Offline

What happens What the hook does
Offline, or no answer within the deadline Uses current.md and tries again at the next prompt. At a session's start it says it is using the last good copy.
Signed out, and the instruction is public Reads it over plain HTTP (Accept: text/markdown), conditionally on its ETag.
Signed out, and the instruction isn't public Holds: … is not public here (a private one is read signed in: instruction login).
The sign-in is refused or expired and can't be refreshed The hook goes on as signed out (the two rows above), and current.md stays in force while nothing newer can be read. Sign in again with instruction agents login.
Nothing has ever been read Says so at a session's start, and the session goes on without the instruction.

A hook never holds a prompt up. Where a session must not run without its instruction, add --fail-closed to the hook's command. With no text at all, it then stops a starting session (continue: false) and blocks a prompt (decision: "block"), with the reason:

Hook command
npx -y @instruction.md/agents hook claude-code --fail-closed
The reason
instruction.md: this project follows acme/support-agent, and no copy of it could be read (no answer within 1500 ms).

--fail-closed acts only when there is no copy at all. A last good copy still counts as a copy.

Signatures

Every version is signed when it is released, with the organization's platform key. With "requireSignature": true (or --require-signature on the setup or the hook), a follower applies a version only when that signature checks out, and the hook's line says (signature verified).

  • Signed in, the publisher's keys are discovered from the registry (instruction://pub/<owner>/keys.json), without revoked keys. A version signed with a revoked key is held.
  • Signed out, a public instruction is read over HTTP, and there is no key discovery: name the keys in keys, or the version is held (no keys to verify …).
  • The follow file can't pin a publisher. instruction watch --publisher <url> and the SDK followers' publisher policy can.

Signing keys, verification and what a signature covers are on Signing and verification.

Sealed instructions

A version of a sealed instruction arrives encrypted. The follower opens it with this machine's key before anything else sees it, so an agent gets the text, never ciphertext. Sealed workspaces are in beta, not yet independently reviewed. The key comes from the environment:

Shell
export INSTRUCTION_MD_SEAL_KEY_FILE=/etc/instruction-md/agent-key.json   # an agent's key file
# or: export INSTRUCTION_MD_SEAL_KEY_COMMAND='vault kv get -field=key secret/instruction-md/agent'
# or, a person's own key: INSTRUCTION_MD_SEAL_PASSPHRASE or INSTRUCTION_MD_SEAL_RECOVERY

Without a key, or with a key the workspace hasn't been given yet, the version is held and the last good copy stays. Sealed instructions are read only signed in, over MCP.

A sealed version reaches the follower without the platform signature (the author's signature is checked when the envelope is opened), so with requireSignature on, it is held as unsigned. Leave requireSignature off for a sealed instruction. Keys and the proxy are on Sealed instructions for developers.

Servers and skills follow too

An instruction can name the MCP servers and skills its agent works with. instruction agents follow … --write for Claude Code or Codex sets apply in the follow file and, when you are signed in, also runs instruction agents apply at once. --no-apply does neither. From then on, when a session starts on a version they weren't written for, the hook runs apply in the background; the app loads them at its next session, and the hook says what changed at the next event. See Servers, skills and accounts.

Check it

instruction agents check says what stops the agent, each with its fix: instruction.md's sign-in, the app's own sign-in, each server's account on this machine. It exits 1 when something does.

Shell
instruction agents check --host claude-code
Output
✓ signed in; this project follows acme/support-agent (v5)
✓ Claude Code 2.1.330, signed in

Nothing stops the agent.

The instruction's Agents card in the editor shows each session's report: which version, and in which app.

Stop following

Remove what the setup wrote. Use either the project's hooks or the instruction.md plugin, never both: both would run for every event.

Shell
instruction agents apply --remove      # the servers and skills apply wrote, and applied.json
rm -r .instruction                      # the follow file and the cached text
# then delete the two hooks that run "… hook claude-code" (@instruction.md/agents or instruction-agents) from .claude/settings.json

With the plugin, uninstall it instead (/plugin uninstall instruction-md@instruction-md in Claude Code). The instruction itself, its versions and the other followers are not affected.

Live updates and their cost

The hooks, the stdio server and @instruction.md/agents/agent only read. Reading is never limited, on any plan, so every session on every machine can follow. instruction watch, the plugin's monitor (instruction watch --lines) and the SDK followers take live updates, and on a plan with a limit only one agent at a time has them in a workspace. Another one still reads on schedule. See Live updates, events and webhooks.

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

Commands that take live updates
instruction watch                                    # the project's follow.json, live
instruction watch instruction://acme/support-agent@stable --out AGENTS.md --block

Common misunderstandings

  • The draft is never followed. Followers read released versions through refs; editing the draft changes nothing an agent receives.
  • A new version doesn't interrupt an answer. It reaches a running session at its next prompt.
  • A hook doesn't need live updates. It reads, so the plan's one live place stays free.
  • current.md is not the source. It is the delivered text; edit the instruction in the editor and release a version.

Questions

Should I commit .instruction/follow.json, current.md and state.json?

Commit follow.json, .instruction/.gitignore, the app's hooks file and, with apply, applied.json. Don't commit current.md, state.json, given/ or applied-note: they are the machine's own copy and state. See Other files.

What happens to my agent when I'm offline or a version can't be verified?

It keeps the last good version in .instruction/current.md and tries again at the next prompt. A version that can't be verified is held, and the session is told once. See Offline and Holds.

How fast does a new version reach a running session?

At its next prompt, once current.md is older than refreshSeconds (60 by default). A session that is idle gets nothing until you write to it, unless the plugin's monitor wakes it. See Hooks.

Can I follow a private instruction without signing in?

No. Signed out, a hook reads only public instructions over HTTP. Sign in with instruction agents login, or give an agent's token in INSTRUCTION_MD_TOKEN. See Offline.

Last checked against the product:

Was this page helpful? Report a problem