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

instruction-agents command reference

For developers who set up and run the agents that follow instructions: every command of @instruction.md/agents (0.4.3), its synopsis, its flags and their defaults, one example, and how it exits. Writing and releasing instructions is the instruction command's: see instruction command reference.

Each synopsis on this page is read from the package's own help (instruction agents --help) when the docs are built. Where a command takes more flags than its line in the help shows, its full usage line, the one it prints on a usage error, follows it.

Run it

The package installs one command, instruction-agents. Three forms run the same commands:

Shell
instruction agents run --help
instruction-agents run --help
npx -y @instruction.md/agents run --help
  • instruction agents <command> works where the instruction.md package is installed. It hands the line to instruction-agents when that is on your PATH, else to npx --yes @instruction.md/agents. See Which package does what.
  • instruction-agents <command> works where @instruction.md/agents is installed (npm i -g @instruction.md/agents). It needs Node.js 20.19 or later.
  • npx -y @instruction.md/agents <command> needs nothing installed. The hooks that follow writes use this form by default (--cli changes it).

--help or -h anywhere prints the help, --version or -v the package's version. In two words used everywhere below, --host is always the agent's app (claude-code, codex, …) and --as is what an instruction becomes there (agent, skill).

Every command

CommandWho runs itWhat the help says it does
instruction agents followPeople runa project's agent follows <uri>: .instruction/follow.json and the app's hooks (instruction agents hook), printed, or --write: written into the project, merged into what is there. HOST: claude-code, codex, qwen-code, droid, devin, gemini-cli, antigravity, copilot, cursor, cline, crush (kiro, junie: said how, by hand) the organization-wide settings for an administrator (Claude Code managed-settings.json, Codex requirements.toml)
instruction agents installPeople runan instruction as the app's own file: a Claude Code agent (.claude/agents/) or skill (.claude/skills/), a Codex skill (.agents/skills/); again to take a new version
instruction agents runPeople runan agent per instruction: runs the command once per active deployment of a rule or a platform, each in a folder of its own with its .instruction/follow.json; starts new ones, stops retired ones, restarts a "restart" one on a new version, leaves a "live" one to its hooks; at most --max or the rule's maxAgents; reports each. {instruction} {name} {dir} in the command are replaced. --once: one pass, waiting for each command to end (a cron job); --dry-run: what it would do --remote-control (claude -p "<task>"): each agent a Claude Code session you control in the Claude app (claude.ai/code, the phone app), named after its instruction; /agents links to it. Needs a claude.ai sign-in (Pro, Max, Team, Enterprise; not an API key), Linux or macOS
instruction agents applyPeople runwrite the instruction's MCP servers and skills into the app's own files (.mcp.json, .claude/skills/, .codex/config.toml, .agents/skills/), its allowed and denied tools as the app's rules; only its own entries are changed or removed (.instruction/applied.json); --approve: Claude Code uses the servers without asking you
instruction agents checkPeople runwhat stops the agent, each with its fix: instruction.md's sign-in, the app's own (Claude Code, Codex), each server's account on this machine; exit 1 when something does
instruction agents accountsPeople runwhat an instruction's `account` means on this machine (~/.config/instruction-md/accounts.json): a variable, a command (your organization's secret store), a sign-in, or your identity provider (XAA); never a value printed
instruction agents signinPeople runsign this machine in to an MCP server (OAuth): a browser here, a code on any device (--device), or the address pasted back
instruction agents loginPeople runsign in to instruction.md (the same sign-in as `instruction login`)
instruction agents whoamiPeople runwho the server says you are
instruction agents hookThe agent's app runsthe app's hooks: the event on stdin; the project's instruction at a session's start, a new version at the next prompt, nothing when nothing changed; exit 0 even offline. HOST: claude-code, codex, qwen-code, droid, devin, gemini-cli, antigravity, copilot, cursor, kiro, cline, junie, crush, goose; --event: the event, for an app that doesn't name it on stdin; auto: told from the event
instruction agents acpThe agent's app runsan ACP proxy (Zed, JetBrains): runs the agent; a session's system prompt carries the instruction where the agent takes one (else its first prompt), a new version at the next prompt, and the instruction mcp bridge among its MCP servers
instruction agents turnThe agent's app runsone turn for a plugin that runs a command (Amp's): JSON {context, notice} on stdout, or nothing; exit 0 even offline
instruction agents credentialThe agent's app runsthe headers for a server, as JSON (Claude Code's headersHelper, Codex's http_headers_helper)
instruction agents mcpThe agent's app runsinstruction.md's stdio MCP server (instruction mcp)

"People run" are the commands you type. "The agent's app runs" are the ones a hook, a plugin or an editor calls; you rarely type them.

Set up a project

instruction agents follow

Synopsis
instruction agents follow <uri> --host HOST [--write] [--require-signature] [--dir D] [--cli CMD] [--no-apply]
instruction agents follow <uri> --host claude-code|codex --managed

Makes a project's agent follow an instruction. It prints, or with --write writes, the follow file .instruction/follow.json, a .instruction/.gitignore that keeps current.md, state.json and given/ out of the repository, and the app's hook files, each merged into what is there. Commit the follow file and the hooks, so everyone working in the project follows the same instruction.

Flag Default Effect
--host <app> required One of claude-code, codex, qwen-code, droid, devin, gemini-cli, antigravity, copilot, cursor, cline, crush, kiro, junie. For kiro and junie it says what to add by hand
--write off Writes the files into the project instead of printing them. A hooks file that isn't JSON is refused (exit 2); one with hooks that aren't instruction.md's is left alone, and the command says what to add
--require-signature off Puts requireSignature: true in the follow file: the hooks take only versions whose signature verifies
--dir <folder> the current folder The project
--cli <command> npx -y @instruction.md/agents How the hooks run this package
--no-apply off For claude-code and codex with --write: doesn't write the instruction's MCP servers and skills now, and doesn't ask the hooks to keep them current
--managed off Prints the organization-wide settings an administrator deploys instead: Claude Code's managed-settings.json or Codex's requirements.toml. Only with --host claude-code or codex, never with --write

With --write for claude-code or codex, and when you are signed in, it also runs apply for that app. Following describes the follow file, and Managed agents the organization-wide settings.

Example
instruction agents follow acme/support-agent@stable --host claude-code --write --require-signature
instruction agents follow acme/support-agent@stable --host codex --managed

Exits 2 for a missing --host or URI, a host it doesn't set up, or --managed with --write.

instruction agents install

Synopsis
instruction agents install [<uri>] --host claude-code|codex --as agent|skill [--name N] [--dir D] [--force]
Usage
usage: instruction agents install [<uri>] --host claude-code|codex --as agent|skill [--name N] [--dir D] [--force]
  (Claude Code: an agent, .claude/agents/, or a skill, .claude/skills/; Codex: a skill, .agents/skills/)

Writes an instruction as one of the app's own files: a Claude Code subagent (.claude/agents/<name>.md), a Claude Code skill (.claude/skills/<name>/SKILL.md), or a Codex skill (.agents/skills/<name>/SKILL.md). Run it again to take a new version. Without <uri>, it takes the instruction the project's follow file names.

Flag Default Effect
--host required claude-code or codex
--as required agent or skill. Codex has no subagent files: --host codex --as agent exits 2
--name <name> the instruction's name The file's name
--dir <folder> the project's root, else the current folder Where the files go
--force off Replaces a file this command didn't write, or one written from another instruction

Signed in, it reads the version from the registry, checking its signature when the follow file asks. Not signed in, it uses the project's cached copy of the instruction it follows. It prints <file> ← owner/name vN, or already when the file is current.

Example
instruction agents install acme/support-agent --host claude-code --as skill
instruction agents install acme/support-agent --host codex --as skill --name support

Exits 2 for a missing --host or --as, or a file it won't replace; 3 when you aren't signed in and nothing is cached.

instruction agents apply

Synopsis
instruction agents apply [<uri>] [--host claude-code|codex|both] [--approve] [--dry-run] [--remove] [--dir D] [--cli CMD]
Usage
usage: instruction agents apply [<uri>] [--host claude-code|codex|both] [--dir D] [--approve] [--dry-run] [--remove] [--cli CMD] [--if-changed] [--quiet] [--note] [--json]

Writes the MCP servers and skills an instruction declares into the app's own files: .mcp.json and .claude/skills/ for Claude Code, .codex/config.toml and .agents/skills/ for Codex. Its allowed and denied tools become the app's own rules. It changes or removes only its own entries, and records them in .instruction/applied.json. Without <uri>, it takes the project's followed instruction.

Flag Default Effect
--host the follow file's apply, else the last apply's, else claude-code claude-code, codex, both, or a comma-separated list
--approve off Claude Code uses the servers without asking you first
--dry-run off Says what it would write and remove, and writes nothing
--remove off Removes everything it wrote, and applied.json
--dir <folder> the project's root, else the current folder The project
--cli <command> npx -y @instruction.md/agents How the app's header command (credential) runs this package
--if-changed off Writes only when the servers and skills changed since the last apply (what the hooks run in the background)
--quiet off Says nothing on stderr
--note off Leaves a note for the hooks to tell the person, when something changed
--json off {dryRun, changed, wrote, removed, conflicts, skipped, notes, applied}
--url, --token as for instruction The MCP server and a token

When a server needs an account this machine doesn't define, it ends with the accounts set or signin command that defines it. Servers, skills and accounts has the whole setup.

Example
instruction agents apply --host both --dry-run
instruction agents apply --host claude-code --approve

Exits 2 for a flag it doesn't know or no instruction to apply, 3 when you aren't signed in.

instruction agents check

Synopsis
instruction agents check [--host claude-code|codex|both] [--fleet] [--no-probe] [--json]
Usage
usage: instruction agents check [--host claude-code|codex|both] [--dir D] [--fleet] [--no-probe] [--json]

Lists what stops the agent, each with its fix: instruction.md's sign-in, the app's own sign-in (Claude Code's, Codex's), and each server's account on this machine. Each line starts with ✓ (fine), ! (a warning) or ✗ (blocks), and the last line says whether anything stops the agent.

Flag Default Effect
--host the last apply's, else the follow file's apply, else claude-code claude-code, codex or both
--dir <folder> the project's root, else the current folder The project
--fleet off Checks as the runner would, with nobody at the terminal
--no-probe off Doesn't call the servers to check the accounts work
--json off {ok, findings}
Example
instruction agents check --host both

Exits 1 when something blocks, 2 for a flag it doesn't know.

Run agents

instruction agents run

Synopsis
instruction agents run (--rule dpr_… | --platform LABEL [--org SLUG]) [--dir D] [--max N] [--interval S] [--once] [--dry-run]
    [--restart-on-exit] [--clean] [--host APP] [--remote-control] -- <command…>
Usage
usage: instruction agents run (--rule dpr_… | --platform LABEL [--org SLUG]) [--dir D] [--max N] [--interval S] [--once] [--dry-run] [--restart-on-exit] [--clean] [--host APP] [--accounts FILE] [--no-apply] [--no-converse] [--remote-control] [--cli CMD] [--url U] [--token T] -- <command…>

The runner. It reads the deployments of one deployment rule (--rule) or of one machine (--platform, the label shown as Where they run), and runs the command after -- once for each active deployment, each in a folder of its own with its own follow file. {instruction}, {name} and {dir} in the command are replaced, and each process gets INSTRUCTION_MD_FOLLOW and INSTRUCTION_MD_DEPLOYMENT. On each pass it starts new deployments, stops retired ones (SIGTERM, then SIGKILL after 10 seconds), restarts a restart one whose version moved, and leaves a live one to its hooks. It reports each deployment to instruction.md.

Flag Default Effect
--rule <dpr_…> one of the two A deployment rule's deployments
--platform <label> one of the two A machine's deployments, from every rule
--org <slug> none With --platform: the organization, by slug or id
--dir <folder> instruction-fleet Where the agents' folders go
--max <n> the rule's maxAgents At most this many agents at once (a whole number above 0)
--interval <s> 60 Seconds between passes (at least 1); a change the server announces starts one at once
--once off One pass, waiting for each command to end: for a cron job
--dry-run off Says what it would do, and does and reports nothing
--restart-on-exit off Starts a command that exits again, with a growing pause
--clean off With --once: removes the folders it made for deployments that are retired or gone
--host <app> told from the command What runs (claude-code, codex, …), for the reports
--accounts <file> the accounts file (INSTRUCTION_MD_ACCOUNTS, else accounts.json in the config folder) This machine's accounts, for the agents' servers
--no-apply off Doesn't write each instruction's servers and skills into its folder
--no-converse off Runs claude -p as a plain process: its questions and permission requests don't reach instruction.md
--remote-control off Each agent is a Claude Code session you control in the Claude app. Not with --once
--cli <command> this command How an agent's app runs this package for a server's credential
--url, --token as for instruction The MCP server and a token

Ctrl-C (or SIGTERM) stops every agent it started. The runner explains rules, folders and states; Remote Control what --remote-control needs; Conversations how questions reach people.

Example
instruction agents run --rule <dpr_… id> --dir ~/agents -- claude -p "Do today's triage." --output-format json
instruction agents run --platform laptop --org acme --once -- codex exec "Check the queue."

Exits 0; 1 when --once saw an agent fail; 2 for a usage error (no command after --, both or neither of --rule and --platform, --org without --platform, a bad --max or --interval, --remote-control with --once); 3 when you aren't signed in; 4 for an organization that isn't yours.

Accounts and sign-ins

instruction agents login

Synopsis
instruction agents login [--device] [--no-browser] [--url U]

The same command as instruction login, with all its flags (--admin, --issuer, --trust-issuer too), and the same token file. Sign in once, with either command. See instruction login.

Example
instruction agents login --device

instruction agents whoami

Synopsis
instruction agents whoami

The same as instruction whoami.

Example
instruction agents whoami

instruction agents accounts

Synopsis
instruction agents accounts [list | set <server[@account]> --env VAR | --command CMD | --oauth | --xaa-idp URL … | host <app> --env VAR
    (--from-env V | --from-command C) | remove <server[@account]>]
Usage
usage:
  instruction agents accounts                                        what each server and host uses on this machine
  instruction agents accounts set <server[@account]> (--env VAR | --command CMD | --oauth | --xaa-idp URL --xaa-client-id ID
        --xaa-subject-env V|--xaa-subject-command C --xaa-server-client-id ID [--xaa-client-secret-env V|--xaa-client-secret-command C]
        [--xaa-server-client-secret-env V|--xaa-server-client-secret-command C] [--xaa-scope S] [--xaa-audience ISS])
        [--header NAME] [--scheme WORD]
  instruction agents accounts host <claude-code|codex> --env VAR (--from-env V | --from-command C)
  instruction agents accounts remove <server[@account]>   |   instruction agents accounts remove-host <name>

What an instruction's account means on this machine: where each server's credential comes from. It is kept in accounts.json in $XDG_CONFIG_HOME/instruction-md/ (else ~/.config/instruction-md/), mode 0600, or in the file INSTRUCTION_MD_ACCOUNTS names. It never holds or prints a secret's value, only where to get it.

Form What it does
accounts or accounts list Each server and host entry, and what it uses
accounts set <server[@account]> … Exactly one source: --env VAR (a variable), --command CMD (a command that prints it, such as your secret store's), --oauth (a sign-in: run signin next), or --xaa-idp URL with its --xaa-… flags (your identity provider)
accounts host <claude-code|codex> --env VAR (--from-env V | --from-command C) The app's own sign-in for the agents run starts: it sets VAR for each
accounts remove <server[@account]> Removes an entry, and its stored sign-in
accounts remove-host <name> Removes a host entry
Flag Default Effect
--header <name> Authorization The header the credential goes in
--scheme <word> Bearer The word before it; an empty one sends the value alone
--file <file> the accounts file Another accounts file
--json off With list: the entries as JSON
Example
instruction agents accounts set github --env GITHUB_TOKEN
instruction agents accounts set linear@work --command "op read op://work/linear/token"
instruction agents accounts host claude-code --env CLAUDE_CODE_OAUTH_TOKEN --from-command "vault kv get -field=token secret/claude"
instruction agents accounts

Exits 2 for a usage error, 4 when remove finds no such entry.

instruction agents signin

Synopsis
instruction agents signin <server> --url U [--account A] [--device] [--no-browser]
Usage
usage: instruction agents signin <server> --url U [--account A] [--device] [--no-browser] [--scope S] [--client-id ID [--client-secret-env V]]

Signs this machine in to an MCP server with OAuth, and keeps the tokens in mcp-tokens.json in $XDG_CONFIG_HOME/instruction-md/ (else ~/.config/instruction-md/), or in the file INSTRUCTION_MD_MCP_TOKENS names. The server's account entry becomes a sign-in.

Flag Default Effect
--url <mcp url> the stored sign-in's, else the last apply's The server
--account <name> none Which of the instruction's accounts this is
--device off A code to approve on any device
--no-browser off Prints the link; you paste the address you land on back
--scope <scopes> the server's The scopes asked for
--client-id <id>, --client-secret-env <VAR> https://instruction.md/agents/cli-client.json where the server takes a client metadata document, else one registered dynamically A client of your own at the server's sign-in service, for one that offers neither (exit 2 says so)
Example
instruction agents signin linear --account work --url https://mcp.example.com/mcp --device

Exits 2 for a usage error or no address.

instruction agents credential

Synopsis
instruction agents credential <server> [--account A] [--url U]

Prints the headers for a server as JSON on stdout, for the app's header command: Claude Code's headersHelper, Codex's http_headers_helper. apply writes those for you. It refuses to print to a terminal, so a secret doesn't end up on screen; instruction agents check tests the same thing without showing it.

Flag Default Effect
--account <name> none The account
--url <mcp url> CLAUDE_CODE_MCP_SERVER_URL The server's address, for a sign-in
--accounts <file> the accounts file Another accounts file (Codex gives a header command no variables but HOME and PATH)
--show off Prints to a terminal anyway

<server> defaults to CLAUDE_CODE_MCP_SERVER_NAME, which Claude Code sets.

Example
instruction agents credential github | jq keys

Exits 2 for a usage error or a terminal, 3 when the credential can't be had, 4 when the machine has no account for the server.

What the agent's app runs

instruction agents hook

Synopsis
instruction agents hook HOST|auto [--event NAME] [--fail-closed] [--follow URI [--require-signature]] [--dir D]
Usage
usage: instruction agents hook claude-code|codex|qwen-code|droid|devin|gemini-cli|junie|crush|copilot|cursor|antigravity|kiro|cline|goose|auto [--event NAME] [--fail-closed] [--dir D] [--follow URI [--require-signature]] [--url U]

What an app's hooks run. The app sends the event as JSON on stdin; the hook answers on stdout. At a session's start it gives the project's instruction whole. At the next prompt after a release it gives the new version, and when nothing changed it prints nothing. It reads the instruction at most every refreshSeconds of the follow file (60 by default), within the deadline, else uses the last good copy. It reads; it never takes a live update. It reports the version each session applied, with the app's name.

Flag Default Effect
HOST required The app: claude-code, codex, qwen-code, droid, devin, gemini-cli, junie, crush, copilot, cursor, antigravity, kiro, cline, goose; or auto, told from the event
--event <name> the event's own For an app that doesn't name the event on stdin
--fail-closed off Blocks the prompt (or stops the session) when there is no text at all, instead of going on without it
--dir <folder> the event's cwd Where to look for the follow file
--follow <uri> the follow file's An instruction by its address, as managed settings run it
--require-signature off With --follow: only versions whose signature verifies
--url <mcp url> the follow file's, else INSTRUCTION_MD_URL The MCP server
--deadline <ms> 1500 How long a read may take before the last good copy is used
Example
echo '{"hook_event_name":"SessionStart","source":"startup","cwd":"'"$PWD"'"}' | instruction agents hook claude-code

Exits 0 every time, offline included, so a prompt never breaks; a missing or unknown HOST exits 1. Following explains what each event gets.

instruction agents acp

Synopsis
instruction agents acp [--follow URI [--require-signature]] [--url U] [--no-bridge] -- <agent command…>
Usage
usage: instruction-agents acp [--follow URI [--require-signature]] [--url U] [--no-bridge] -- <agent command> [args…]

An Agent Client Protocol proxy, for Zed, JetBrains and other ACP clients: the client runs it in place of the agent, and it runs the agent after --. Every message passes through unchanged, except that a new session gets the instruction in its system prompt where the agent takes one (else before its first prompt), and a new version arrives at the next prompt. It also adds the instruction mcp stdio server to the session's MCP servers, unless --no-bridge. It reports the version a session applied with the app acp.

Example
instruction agents acp --follow acme/support-agent@stable -- <your agent's ACP command>

Exits with the agent's code; 127 when the agent can't be started; 1 for a usage error.

instruction agents turn

Synopsis
instruction agents turn <app> --session ID [--start [--source S]] [--cwd D] [--follow URI]
Usage
usage: instruction-agents turn <app> --session ID [--start [--source S]] [--cwd D] [--follow URI [--require-signature]] [--url U]

One turn for a plugin that can only run a command, such as Amp's. It prints {"context": …, "notice": …} as JSON on stdout, or nothing when there is nothing new. --start marks a session's start (--source says why), --cwd is where to look for the follow file, and --deadline <ms> bounds the read.

Example
instruction agents turn amp --session <session id> --start --cwd "$PWD"

Exits 0 every time; a missing app or --session exits 1.

instruction agents mcp

Synopsis
instruction agents mcp …

The CLI's stdio MCP server, the same as instruction mcp, with the same flags: see instruction mcp.

Example
instruction agents mcp --root .

The pi extension

The package is also a pi extension. Install it into pi:

Shell
pi install npm:@instruction.md/agents

Before every run, it sets the system prompt section instruction to the current text of the instruction the project follows (its follow file, else INSTRUCTION_MD_FOLLOW). pi sends a changed section as a patch to the running session, so a new version arrives at the next prompt and an unchanged one costs nothing. It tells you of a new version, and reports the version each session applied with the app pi. It reads the text as the hooks do. Other agents compares it with the other apps.

The SDK entry

@instruction.md/agents/agent gives an agent you build with an SDK (the Claude Agent SDK, the Codex SDK, or your own loop) the text of an instruction, and tells you between turns when a new version was released.

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

const ins = await follow("instruction://acme/support-agent@stable", { requireSignature: true });

for await (const message of query({
  prompt: "Answer the oldest open ticket.",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code", append: ins.text },
    hooks: {
      UserPromptSubmit: [{
        hooks: [async () => (await ins.changedSinceLastTurn())
          ? { hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: ins.updateBlock() } }
          : {}],
      }],
    },
  },
})) console.log(message);

await ins.close();

follow(uri, options) reads the version now, and throws when there is none it can hand over. Its options:

Option Default Effect
url INSTRUCTION_MD_URL, else https://instruction.md/mcp The MCP server
token INSTRUCTION_MD_TOKEN A bearer token, or a function that returns one before each read. An agent gets one from its agent credential
client none Your own MCP client (with readResource and callTool); url and token are then unused
requireSignature false Only versions whose author signature verifies
keys the publisher's The author keys accepted
refreshSeconds 60 How long a version is used before the next read
deadlineMs 5000 How long a read may take before the version in hand is kept

The result has uri, label, text (the delivered text), version, versionId, digest, verified and current, and these methods: refresh() reads now and says whether a new version came; changedSinceLastTurn() reads once refreshSeconds passed and says whether the version differs from the one the model was last given; updateBlock() is what to tell the model about that version; contextBlock() is the version as a block for the start; close() stops. It holds no live connection, and a read that fails keeps the version in hand.

Earlier names

The help says:

instruction agents --help
Earlier names still work: connect --with-hooks (follow), sync --as claude-agent|claude-skill|codex-skill (install), fleet (run), doctor (check).

The same commands still answer under the instruction command's old top-level names, such as instruction hook claude-code in a project's committed hooks: see Handed to @instruction.md/agents. What changed lists when each name changed.

Exit codes

Command 0 Other codes
follow, install, login, whoami done the instruction codes: 2 usage or a refused input, 3 not signed in, and the rest on Exit codes
run done, or stopped 1 --once saw an agent fail, 2 usage, 3 not signed in, 4 no such organization
apply done 1 error, 2 usage, 3 not signed in
check nothing blocks 1 something blocks, 2 usage
accounts done 2 usage, 4 no such entry
signin signed in 2 usage, others as the sign-in failed
credential headers printed 2 usage or a terminal, 3 no credential, 4 no account
hook, turn always, offline included 1 usage only
acp the agent's own code 1 usage, 127 the agent didn't start
an unknown command 2

Last checked against the product:

Was this page helpful? Report a problem