Codex
Codex, OpenAI's coding agent, can follow an instruction from instruction.md in two ways: for one project, through
hooks, or for everything you do in Codex, through your own AGENTS.md. Either way, a new version reaches a
session that is already running.
What you need: Node.js 18 or later. The commands on this page run the
instruction.mdpackage from npm withnpx; nothing else to install.
Using another tool? See Other coding agents.
For a project
In your project's folder, signed in (instruction login), run:
instruction connect --host codex instruction://acme/support-agent@stable --with-hooks --write It writes, keeping anything already there:
.instruction/follow.json: which instruction the project follows. Commit it.- Two hooks in
.codex/hooks.json: one when a session starts, one each time you send a prompt. .instruction/.gitignore, so the copy the hooks keep stays out of git.
Codex asks you to trust each hook the first time it sees it, and again if it changes. Trust them once.
{
"follow": "instruction://acme/support-agent@stable",
"requireSignature": true,
"refreshSeconds": 60,
"maxInjectChars": 9000
} {
"hooks": {
"SessionStart": [
{ "matcher": "startup|resume|clear|compact",
"hooks": [{ "type": "command", "command": "npx -y instruction.md hook codex", "timeout": 10, "additionalContextLimit": 0 }] }
],
"UserPromptSubmit": [
{ "hooks": [{ "type": "command", "command": "npx -y instruction.md hook codex", "timeout": 5, "additionalContextLimit": 0 }] }
]
}
} "additionalContextLimit": 0 lets the hook give Codex the whole instruction: Codex otherwise cuts what a hook
adds at about 2,500 tokens. The fields of the binding file are the same as
in Claude Code.
What you see when the instruction changes
When a session starts, the hook gives Codex the instruction's whole text. At each prompt it checks the version, and adds nothing unless it changed. When it did, you see one line:
instruction.md: acme/support-agent v4 → v5 (signature verified) and Codex receives the new version, 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 hook never holds up a prompt: offline or slow, it uses the last good version it kept, and tries again next time.
--fail-closed stops a prompt that has no instruction to give instead. With
"requireSignature": true it applies only versions whose signature checks out. These work as
in Claude Code.
For everything you do in Codex
Codex reads your own ~/.codex/AGENTS.md again before each request it makes to the model, and when the file
has changed, it tells the model the new text replaces the old. So an instruction kept in that file reaches a running
session even in the middle of a task. Keep it current with:
instruction watch instruction://acme/personal@latest --out ~/.codex/AGENTS.md --block --block writes only between two marker lines, leaving the rest of your AGENTS.md as you wrote
it, and each write is atomic, so Codex never reads half a file:
Your own notes stay here, as you wrote them.
<!-- instruction.md:begin uri="instruction://acme/personal@latest" version="v7" digest="sha256:41ab…" -->
# Personal
…
<!-- instruction.md:end -->
If a ~/.codex/AGENTS.override.md exists, Codex reads it instead, and the command warns you. A project's own
AGENTS.md is read when a session starts only, so use the hooks above for a project.
instruction watch keeps a live connection while it runs; on the Community plan one agent or app has one at
a time. The hooks only read, which is never limited.
The MCP server
Codex speaks an earlier version of MCP than instruction.md's server (2026-07-28), so it connects through the command line's own MCP server, which talks to the registry for it:
# ~/.codex/config.toml (or .codex/config.toml in a trusted project)
[mcp_servers.instruction-md]
command = "npx"
args = ["-y", "instruction.md", "mcp", "--follow", "instruction://acme/support-agent@stable"]
Codex can then read the followed instruction as the resource instruction://current when it needs to. It
doesn't subscribe to changes, so the hooks or AGENTS.md remain how a new version arrives.
As a skill
instruction sync instruction://acme/support-agent@stable --as codex-skill # .agents/skills/support-agent/SKILL.md Codex notices the change when you run it again for a newer version.
In your own agent, with the Codex SDK
import { Codex } from "@openai/codex-sdk";
import { follow } from "instruction.md/agent";
const ins = await follow("instruction://acme/support-agent@stable");
const codex = new Codex({ config: { developer_instructions: ins.text } });
const thread = codex.startThread();
await thread.run("Answer the open tickets"); The plugin
The plugin that carries the hooks, the MCP server and the skill for Claude Code has a manifest of Codex's own too, so
Codex runs the same hooks. Install it from instruction.md's marketplace
(github.com/instruction-md/plugins); Codex asks you once to
approve a plugin's hooks (/hooks).
codex plugin marketplace add instruction-md/plugins
codex plugin add instruction-md@instruction-md
# then approve its hooks once, in Codex: /hooks Who follows it, from where
Each session's hook reports the version it applied, and that it was in Codex: the instruction's Agents card counts its followers by app, and managed agents shows the whole organization.