Managed agents
For administrators who put one instruction on every developer's Claude Code or Codex through the tools' own managed settings, so nobody sets anything up and nobody can switch it off, and who then check which version each machine applied.
A single project can follow an instruction on its own, with a committed follow file and hooks (see Claude Code and Codex). The managed path described here doesn't need a follow file. Each managed hook names the instruction with --follow, so it applies in every folder on the machine.
Before you start
- The instruction. It is released, and the ref the machines follow exists.
stableis never made for you: create it withinstruction refs <id> set stable v1, as refs explains. The samples on this page followinstruction://acme/support-agent@stable. - Node.js 20.19 or later on every machine. Both
instruction.mdand@instruction.md/agentsrequire it. The hooks run withnpxunless you install the package (see Node and npx). - A way to push files. MDM, a configuration tool, a machine image, or each tool's own server-managed settings.
- A sign-in on each machine, unless the instruction is public. See Sign each machine in.
- For the audit: you are an admin or the owner of the organization.
Print your organization's files
--managed prints the settings for one instruction and writes nothing. Run it on your own machine, then deploy what it prints:
instruction agents follow instruction://acme/support-agent@stable --host claude-code --managed
instruction agents follow instruction://acme/support-agent@stable --host codex --managed It accepts --host claude-code or --host codex only, and refuses --write and --with-hooks beside it. --url changes the MCP server address the printed MCP entries use. --cli <command> changes the command the hooks run (default npx -y @instruction.md/agents). The no-install form of the same command is npx -y @instruction.md/agents follow <uri> --host claude-code --managed.
Claude Code
Claude Code reads a managed-settings.json that people on the machine can't change:
| System | Folder |
|---|---|
| Linux | /etc/claude-code/ |
| macOS | /Library/Application Support/ClaudeCode/ |
| Windows | C:\Program Files\ClaudeCode\ |
| Any | your organization's server-managed settings in Claude Code |
--host claude-code --managed prints two files with a comment above each:
// managed-settings.json — /etc/claude-code/ (Linux), /Library/Application Support/ClaudeCode/ (macOS),
// C:\Program Files\ClaudeCode\ (Windows), or your organization's server-managed settings.
// Every session on the machine gets instruction://acme/support-agent@stable at its start and each new version at its next prompt.
// Add "allowManagedHooksOnly": true to let only managed hooks run. The plugin's marketplace is published with the plugin.
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume|clear|compact",
"hooks": [
{
"type": "command",
"command": "npx -y @instruction.md/agents hook claude-code --follow instruction://acme/support-agent@stable",
"timeout": 10
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "npx -y @instruction.md/agents hook claude-code --follow instruction://acme/support-agent@stable",
"timeout": 5
}
]
}
]
},
"enabledPlugins": {
"instruction-md@instruction-md": true
},
"extraKnownMarketplaces": {
"instruction-md": {
"source": {
"source": "github",
"repo": "instruction-md/plugins"
}
}
}
}
// managed-mcp.json, beside it: the instruction.md server (https://instruction.md/mcp) for every session
{
"mcpServers": {
"instruction-md": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"instruction.md",
"mcp",
"--follow",
"instruction://acme/support-agent@stable",
"--url",
"https://instruction.md/mcp"
]
}
}
} The first file is managed-settings.json:
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume|clear|compact",
"hooks": [
{
"type": "command",
"command": "npx -y @instruction.md/agents hook claude-code --follow instruction://acme/support-agent@stable",
"timeout": 10
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "npx -y @instruction.md/agents hook claude-code --follow instruction://acme/support-agent@stable",
"timeout": 5
}
]
}
]
},
"enabledPlugins": {
"instruction-md@instruction-md": true
},
"extraKnownMarketplaces": {
"instruction-md": {
"source": {
"source": "github",
"repo": "instruction-md/plugins"
}
}
}
} hooks:SessionStart(matcherstartup|resume|clear|compact, 10-second timeout) gives the whole text when a session starts or its context is wiped.UserPromptSubmit(5 seconds) gives a new version at the next prompt of a session that is already running.enabledPluginsandextraKnownMarketplaces: install the instruction.md plugin for everyone, from theinstruction-md/pluginsrepository on GitHub.
The printed comment names one key it leaves out, allowManagedHooksOnly. With it set, only managed hooks run: a project's or a person's own hooks don't. Add it when that is what you want. It also stops the hooks of projects that follow their own instruction with a follow file:
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume|clear|compact",
"hooks": [
{
"type": "command",
"command": "npx -y @instruction.md/agents hook claude-code --follow instruction://acme/support-agent@stable",
"timeout": 10
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "npx -y @instruction.md/agents hook claude-code --follow instruction://acme/support-agent@stable",
"timeout": 5
}
]
}
]
},
"enabledPlugins": {
"instruction-md@instruction-md": true
},
"extraKnownMarketplaces": {
"instruction-md": {
"source": {
"source": "github",
"repo": "instruction-md/plugins"
}
}
},
"allowManagedHooksOnly": true
} The second file is managed-mcp.json, in the same folder. It gives every session the instruction.md MCP server, run on the machine as instruction.md mcp --follow <uri>:
{
"mcpServers": {
"instruction-md": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"instruction.md",
"mcp",
"--follow",
"instruction://acme/support-agent@stable",
"--url",
"https://instruction.md/mcp"
]
}
}
} The hooks don't need this server: they read the instruction themselves. Claude Code treats a managed MCP file as the fixed set of servers for the machine, so leave it out, or add your people's other servers to it, before you deploy it. Check Claude Code's own documentation on managed MCP servers.
Codex
Codex reads managed requirements from /etc/codex/requirements.toml, or from your organization's managed configuration. --host codex --managed prints the file:
# requirements.toml — /etc/codex/requirements.toml, or your organization's managed configuration.
# Every Codex session on the machine gets instruction://acme/support-agent@stable at its start and each new version at its next prompt;
# managed hooks need no approval from the person. Add allow_managed_hooks_only = true to run only these.
[features]
hooks = true
[hooks]
managed_dir = "/etc/codex/hooks"
[[hooks.SessionStart]]
matcher = "startup|resume|clear|compact|fork"
[[hooks.SessionStart.hooks]]
type = "command"
command = "npx -y @instruction.md/agents hook codex --follow instruction://acme/support-agent@stable"
timeout = 10
additionalContextLimit = 0
[[hooks.UserPromptSubmit]]
[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "npx -y @instruction.md/agents hook codex --follow instruction://acme/support-agent@stable"
timeout = 5
additionalContextLimit = 0
# only this instruction.md server (https://instruction.md/mcp) may run, started as this command
[mcp_servers.instruction-md.identity]
command = "npx" [features] hooks = trueturns hooks on, and people can't turn them off.[hooks]holds the managed hooks, withmanaged_dir = "/etc/codex/hooks"as printed.- The two hooks have the same commands as Claude Code's. The
SessionStartmatcher addsfork.additionalContextLimit = 0stops Codex from cutting the hook's text at its default of about 2,500 tokens; the hook keeps it under 9,000 characters itself. - Managed hooks need no approval from the person. To run only these hooks, add
allow_managed_hooks_only = true, as the printed comment says. [mcp_servers.instruction-md.identity]is an allowlist entry: the instruction.md server may run only when started asnpx. A Codex allowlist lets only the servers it names run, so merge this entry into your existing list.
Codex may take a while to pick up a changed cloud policy in a task that is already running.
Which package does what
| Part | Package | Command it runs |
|---|---|---|
| The hooks (both tools) | @instruction.md/agents |
instruction-agents hook claude-code or hook codex, with --follow <uri> |
The MCP server (Claude Code's managed-mcp.json) |
instruction.md |
npx -y instruction.md mcp --follow <uri> --url <server> (instruction mcp when installed) |
| Printing the files | either | instruction agents follow … --managed, which instruction hands to @instruction.md/agents |
A managed hook keeps its copy of the instruction in the person's cache, not in a project. One folder is kept per followed address:
~/.cache/instruction-md/follow/<hash>/current.md # or $XDG_CACHE_HOME/instruction-md/…, or $INSTRUCTION_MD_CACHE/…
~/.cache/instruction-md/follow/<hash>/state.json Only what your publisher signed
Every version is signed with your organization's platform key when it is released. To make the machines apply only a version whose signature they verified, add --require-signature to both hook commands after --follow <uri>. --managed doesn't print it:
npx -y @instruction.md/agents hook claude-code --follow instruction://acme/support-agent@stable --require-signature
npx -y @instruction.md/agents hook codex --follow instruction://acme/support-agent@stable --require-signature A version that doesn't verify is held: the hook keeps giving the last version that did. To stop an unsigned version from becoming stable at all, gate the ref as well: instruction refs <id> gate stable --require-signature. Signing and verification explains the keys and the gate.
Sign each machine in
The hook reads a private or organization-only instruction as the person signed in on the machine, and it reports what it applied as them. Each person signs in once:
instruction agents login
# a machine without a browser (SSH, a container): a code you enter on another device
instruction agents login --device instruction agents login and instruction login share one sign-in. A token in INSTRUCTION_MD_TOKEN works too. Without a sign-in, the hook reads only a public instruction, over plain HTTP, and reports nothing.
Push the files
Release the instruction and create the ref
Release the version the machines get, and create the ref they follow (
instruction refs <id> set stable v1).Print the files
Run
--managedfor each tool. Edit in--require-signature,allowManagedHooksOnlyorallow_managed_hooks_onlyif you want them.Deploy them
Put them in the folders above with your MDM, configuration tool or image, or paste them into the tool's server-managed settings.
Sign each person in
Each person runs
instruction agents loginonce (see Sign each machine in).Check a machine
Run the hook by hand, then look at the instruction's Agents card: the machine shows with the version it applied.
Claude Code fetches server-managed settings when it starts and every hour after that.
Check a machine
Run the hook by hand, the way Claude Code runs it when a session starts:
echo '{"hook_event_name":"SessionStart","source":"startup","session_id":"managed-check"}' \
| npx -y @instruction.md/agents hook claude-code --follow instruction://acme/support-agent@stable It prints one JSON object. With the instruction read, hookSpecificOutput.additionalContext starts with "These are this project's instructions from instruction.md (…). Follow them." and holds the text in an <instruction uri="…" version="…" digest="…"> element. With nothing to give, systemMessage says why (see If it doesn't work). The hook exits 0 either way.
The hook gives each version to a session once. Run the same check again with the same session_id and it prints nothing, because that session already holds the version. Change session_id to see the text again.
instruction agents check --host claude-code (or codex, or both) lists what stops the agent on that machine, each with its fix: instruction.md's sign-in, the tool's own sign-in, and each server's account. It exits 1 when something does.
In a session, a new version shows as one line, for example instruction.md: acme/support-agent v4 → v5 (signature verified).
Roll forward, roll back, remove
The managed files name a ref, so you change what every machine follows by moving the ref, not by pushing files again.
- Roll forward. Release, then move
stable. Each running session gets the new version at its next prompt after its copy is more than 60 seconds old.
instruction publish <id> --message "Say what changed"
instruction refs <id> set stable v6 - Roll back. Move
stableback to an earlier version:
instruction refs <id> set stable v5 - Pin. To hold the machines on one version whatever the refs do, follow it by number in the files,
instruction://acme/support-agent@v5, and push them again. - Remove. Delete the two hook entries (and
managed-mcp.json, if you deployed it) from the managed files and push them. The cached copies in~/.cache/instruction-md/follow/can then be deleted.
Offline machines, proxies and Node
Offline machines
A hook reads at most every 60 seconds, and waits at most 1.5 seconds for an answer. When it can't read, it gives the last good copy from the cache and says so once at the session's start. It never holds a prompt up, and it exits 0. Offline covers this for every follower.
A machine that has never read the instruction has no copy. Its sessions go on without the instruction, and the start of each session says so. To refuse work instead, add --fail-closed to both hook commands: with no copy at all, a session doesn't start and a prompt is blocked, with the message "instruction.md: this project follows …, and no copy of it could be read (…)".
Proxies
The hooks and the MCP server have no proxy option of their own. Each machine must reach https://instruction.md/mcp (or your server) over HTTPS from Node.js, and, while the hooks run through npx, your npm registry.
Node and npx
The first npx -y @instruction.md/agents on a machine downloads the package, which can take longer than the hook's 10-second timeout. Install the package with the image or MDM instead, and print the files with --cli:
npm i -g @instruction.md/agents
instruction agents follow instruction://acme/support-agent@stable --host claude-code --managed --cli instruction-agents The hooks then run:
instruction-agents hook claude-code --follow instruction://acme/support-agent@stable A self-hosted server
--url sets the address of the MCP entries, but not of the hooks. On a self-hosted server, add --url to both hook commands, or set INSTRUCTION_MD_URL on the machines:
npx -y @instruction.md/agents hook claude-code --follow instruction://acme/support-agent@stable --url https://instructions.example.com/mcp Who applied what
Every signed-in hook reports the version it applied and the app it ran in. You see the reports in three places:
- The instruction's Agents card in the editor. Its line counts them by app ("By app: 12 in Claude Code and 3 in Codex"), and it shows who is behind and who is paused.
- The instruction's activity: "Dana Kim applied v5 of Support agent in Claude Code (instruction.md hook (claude-code) on dana-mbp)".
- The audit trail, filtered to those reports. The audit needs administrator permission, which
instruction login --adminasks for:
instruction login --admin
instruction audit --org acme --types binding.reported --from 2026-11-01T00:00:00Z It prints the last 100 records. For all of them, as NDJSON or CSV:
instruction audit export --org acme --types binding.reported --format csv --out applied.csv A Claude Code or Codex session that reads the instruction over MCP without a hook is counted by the app its MCP client names. The server doesn't check the plan for the audit: an organization's owners and admins can query it on every plan. The audit covers its filters and its export.
What this doesn't do
- Neither tool lets anything change the system prompt in the middle of a session. The instruction arrives as context the agent is told to follow: at the start, and with the next prompt after a release. It isn't a lock on what the agent can do. Use each tool's permission settings for that.
- A machine with no sign-in can't read a private instruction, and nothing it does is reported.
- The managed files follow one instruction. To give different teams different instructions, push different files to their machines.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
instruction.md: couldn't read <instruction> (…); this session goes on without it |
The hook got no text and has no copy: no sign-in, no network, or a ref that doesn't exist. | Sign the person in, check the address, create the ref. Run the check. |
--managed is for --host claude-code or codex |
Another host was named. | Managed settings exist for those two tools only. Other tools follow a project's file: Other coding agents. |
--managed prints an organization's settings, for an administrator to deploy; it writes nothing |
--write or --with-hooks was given with --managed. |
Leave them out, and deploy the printed files yourself. |
| A session started, but the hook timed out | The first npx download took longer than 10 seconds. |
Install @instruction.md/agents on the machines and print with --cli instruction-agents. |
| The Agents card doesn't show a machine | The hook isn't signed in, or the report didn't fit in the hook's time. | Sign in. A report is sent again at the next event. |
| Still stuck | Ask us. |
Questions
Can people turn the hooks off?
Not the managed ones: both tools load managed settings above a person's and a project's. With allowManagedHooksOnly (Claude Code) or allow_managed_hooks_only (Codex), their own hooks don't run either.
Do I need the managed MCP file?
No. The hooks read the instruction themselves. The MCP file gives each session instruction.md's tools as well. See Claude Code.
How fast does a release reach a running session?
At its next prompt, once the copy on the machine is more than 60 seconds old. A hook never waits more than 1.5 seconds for a read. See Roll forward, roll back, remove.
What happens on a machine that is offline?
It keeps giving the last good copy. A machine that never read the instruction goes on without it, unless the hooks run with --fail-closed. See Offline machines.
Related
- Roll out an instruction to your developers, in plain words
- Following an instruction
- Claude Code and Codex, for one project
- Signing and verification
- The audit