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.md package from npm with npx; nothing else to install.

Using another tool? See Other coding agents.

For a project

In your project's folder, signed in (instruction login), run:

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

.instruction/follow.json
{
  "follow": "instruction://acme/support-agent@stable",
  "requireSignature": true,
  "refreshSeconds": 60,
  "maxInjectChars": 9000
}
.codex/hooks.json
{
  "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:

Codex
instruction.md: acme/support-agent v4 → v5 (signature verified)

and Codex receives the new version, marked as replacing the old one in full:

What Codex receives
<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:

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

~/.codex/AGENTS.md
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:

config.toml
# ~/.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

Shell
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

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