Cette page n’est pas encore traduite.

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.

How one instruction reaches every managed machine, and how each machine's applied version comes back.

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. stable is never made for you: create it with instruction refs <id> set stable v1, as refs explains. The samples on this page follow instruction://acme/support-agent@stable.
  • Node.js 20.19 or later on every machine. Both instruction.md and @instruction.md/agents require it. The hooks run with npx unless 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.

--managed prints the settings for one instruction and writes nothing. Run it on your own machine, then deploy what it prints:

Shell
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:

Output
// 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:

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 (matcher startup|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.
  • enabledPlugins and extraKnownMarketplaces: install the instruction.md plugin for everyone, from the instruction-md/plugins repository 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:

managed-settings.json, only managed hooks
{
  "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>:

managed-mcp.json
{
  "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
# 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 = true turns hooks on, and people can't turn them off.
  • [hooks] holds the managed hooks, with managed_dir = "/etc/codex/hooks" as printed.
  • The two hooks have the same commands as Claude Code's. The SessionStart matcher adds fork. additionalContextLimit = 0 stops 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 as npx. 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
~/.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:

Hook commands
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:

Shell
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

  1. 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).

  2. Print the files

    Run --managed for each tool. Edit in --require-signature, allowManagedHooksOnly or allow_managed_hooks_only if you want them.

  3. 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.

  4. Sign each person in

    Each person runs instruction agents login once (see Sign each machine in).

  5. 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:

Shell
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.
Shell
instruction publish <id> --message "Say what changed"
instruction refs <id> set stable v6
  • Roll back. Move stable back to an earlier version:
Shell
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:

Shell
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:

Hook command
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:

Hook command
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 --admin asks for:
Shell
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:

Shell
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.

Last checked against the product:

Was this page helpful? Report a problem