لم تُترجم هذه الصفحة بعد.

Codex

This page is for developers who use OpenAI's Codex. It shows how to make Codex follow an instruction from instruction.md, for one project or for everything you do in Codex, so that a new version reaches a session that is already running.

Per project or everywhere

Per project Everywhere
What follows the instruction Every Codex session in one repository, for everyone who works in it Every Codex session you start, in any folder, on this machine
How Two hooks in .codex/hooks.json and .instruction/follow.json, committed instruction watch keeps a region of your ~/.codex/AGENTS.md current
A new version arrives At your next prompt Before Codex's next request to the model, even in the middle of a task
Live updates No: the hooks only read Yes: watch takes a live-update place while it runs
Setup instruction agents follow … --host codex --write instruction watch … --block, kept running as a service

Both can run at once: the project's hooks and your own AGENTS.md are separate instructions to Codex.

What you need: Node.js 20.19 or later. The instruction command is the instruction.md package (npm i -g instruction.md, 0.11.0 or later). instruction agents … hands over to @instruction.md/agents (0.4.1 or later). Without installing anything, the same commands run as npx -y @instruction.md/agents …:

Shell
npx -y @instruction.md/agents follow instruction://acme/support-agent@stable --host codex --write

Sign in once with instruction login (instruction login --device on a machine without a browser). instruction agents login is the same sign-in. A public instruction can be followed without signing in.

Per project: the hooks

In your project's folder, run:

Shell
instruction agents follow instruction://acme/support-agent@stable --host codex --write

It writes these files, merged into what is already there. A hook that already runs the same command is not added twice.

  • .instruction/follow.json: the instruction the project follows. Commit it.
  • .codex/hooks.json: two hooks, one when a session starts and one each time you send a prompt. Commit it.
  • .instruction/.gitignore: keeps the copy the hooks fetch, and their state, out of git.
.codex/hooks.json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact|fork",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @instruction.md/agents hook codex",
            "timeout": 10,
            "additionalContextLimit": 0
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @instruction.md/agents hook codex",
            "timeout": 5,
            "additionalContextLimit": 0
          }
        ]
      }
    ]
  }
}
.instruction/.gitignore
current.md
state.json
given/
  • The SessionStart matcher covers every way a session begins: startup, resume, clear, compact and fork. After a compaction or a fork, the session gets the whole text again.
  • "additionalContextLimit": 0 turns off Codex's own cut. Codex otherwise cuts what a hook adds at about 2,500 tokens. The hook keeps its text under the follow file's maxInjectChars (9,000 characters by default). A longer instruction is cut there, with a line telling the model to read the rest in .instruction/current.md.
  • The timeouts are in seconds: 10 at a session's start, 5 at a prompt.

With --require-signature, the follow file also says that only versions whose signature checks out are applied:

Shell
instruction agents follow instruction://acme/support-agent@stable --host codex --write --require-signature
.instruction/follow.json
{
  "follow": "instruction://acme/support-agent@stable",
  "requireSignature": true,
  "apply": [
    "codex"
  ]
}

Every field of the follow file, and the other files in .instruction/, are on How following works. Without --write, the command prints the same files for you to add yourself, together with Codex's MCP settings:

Shell
instruction agents follow instruction://acme/support-agent@stable --host codex

Other flags: --dir D sets up another folder, --cli CMD changes how the hook runs the agents' command (--cli instruction-agents once @instruction.md/agents is installed globally), and --no-apply skips the servers and skills below.

Servers and skills

When you are signed in, --write also runs instruction agents apply --host codex. It writes the MCP servers the instruction names into .codex/config.toml and its skills into .agents/skills/. The follow file's apply list (["codex"]) makes the hook write them again, in the background, when a session starts on a version they weren't written for. Codex reads them at its next session. Codex reads a project's .codex/config.toml once you trust the folder.

Shell
instruction agents apply --host codex            # .codex/config.toml and .agents/skills/
instruction agents apply --host codex --dry-run  # what it would write
instruction agents apply --host codex --remove   # take its own entries out again

What apply writes, accounts and sign-ins for those servers are on Servers, skills and accounts.

Trust the hooks

The command ends with what to commit and this note:

Shell
Codex runs a project's hooks once the project is trusted, and asks you to trust each hook definition (/hooks).

Start Codex in the project and trust the folder when it asks. Codex then asks you to trust each hook definition the first time it sees it, and again when a hook's command changes, for example after you add --fail-closed. Open /hooks in Codex to see the hooks and trust them.

Codex asks you to trust each hook once, and again when its command changes.

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 while it is current. When someone releases a new version, you see one line:

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

With your next prompt, 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 reads the instruction at most every refreshSeconds (60 by default), and waits at most 1.5 seconds. Offline, slow or signed out, it uses the last good copy it kept and tries again next time, so it never holds up a prompt. It always exits 0, unless you add --fail-closed to both hook commands. Then it stops a prompt, or a session, when there is no copy of the instruction at all, and says why (instruction.md: this project follows acme/support-agent, and no copy of it could be read (…)):

.codex/hooks.json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact|fork",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @instruction.md/agents hook codex --fail-closed",
            "timeout": 10,
            "additionalContextLimit": 0
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @instruction.md/agents hook codex --fail-closed",
            "timeout": 5,
            "additionalContextLimit": 0
          }
        ]
      }
    ]
  }
}

How the hooks read, hold and recover is on How following works.

Everywhere: your own AGENTS.md

Codex 0.156.0 and later read your own ~/.codex/AGENTS.md again before each request they make to the model. 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 and leaves the rest of your AGENTS.md as you wrote it. Each write replaces the file in one step, so Codex never reads half a file. The region carries the version and the digest of the text in it:

~/.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 -->
watch --block keeps only its own region of your AGENTS.md.
  • If ~/.codex/AGENTS.override.md exists, Codex reads it instead of AGENTS.md, and watch warns you. Delete or rename the override file, or point --out at it.
  • When CODEX_HOME is set, Codex reads AGENTS.md from that folder instead of ~/.codex. Point --out there.
  • A project's own AGENTS.md is read only when a session starts. For a project, use the hooks above.
  • watch prints a line for each version it applies, and hold: … when it keeps the version it has (for example, a version whose signature doesn't check out with --require-signature).

On Windows, Codex's folder is %USERPROFILE%\.codex. In PowerShell:

PowerShell
instruction watch instruction://acme/personal@latest --out "$env:USERPROFILE\.codex\AGENTS.md" --block

Live updates

watch asks for live updates, so a release reaches the file within moments. On the Community plan, one agent or app has live updates at a time:

Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited

When another agent or app has them, watch says live updates are taken: … Still reading on schedule. and goes on reading every --freshness seconds (60 by default). The hooks never take live updates: reading is never limited. The rule is on Live updates.

Keep watch running

watch runs until you stop it. To keep it running after you close the terminal and restart the computer, run it as a service of your user. It uses the sign-in you made with instruction login, and renews it as it runs. Find the full path of the command with command -v instruction (macOS, Linux) and use it in place of <path to instruction>.

The instruction command starts with #!/usr/bin/env node, so node must be on the service's PATH. A service doesn't read your shell's profile. If command -v node prints a folder that isn't /usr/bin or /usr/local/bin (nvm, Homebrew on Apple silicon), add that folder: an Environment=PATH=… line under [Service] on Linux, the PATH entry of the plist on macOS.

Linux: a systemd user service

~/.config/systemd/user/instruction-watch-codex.service
# ~/.config/systemd/user/instruction-watch-codex.service
[Unit]
Description=instruction.md: keep ~/.codex/AGENTS.md current
After=network-online.target

[Service]
# the absolute path that `command -v instruction` prints; node must be on its PATH (Environment=PATH=…)
ExecStart=<path to instruction> watch instruction://acme/personal@latest --out %h/.codex/AGENTS.md --block
Restart=always
RestartSec=30

[Install]
WantedBy=default.target
Shell
systemctl --user daemon-reload
systemctl --user enable --now instruction-watch-codex.service
journalctl --user -u instruction-watch-codex.service -f   # what it applied

macOS: a launchd agent

~/Library/LaunchAgents/md.instruction.watch-codex.plist
<?xml version="1.0" encoding="UTF-8"?>
<!-- ~/Library/LaunchAgents/md.instruction.watch-codex.plist -->
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>md.instruction.watch-codex</string>
  <key>ProgramArguments</key>
  <array>
    <string><path to instruction></string>
    <string>watch</string>
    <string>instruction://acme/personal@latest</string>
    <string>--out</string>
    <string>/Users/<you>/.codex/AGENTS.md</string>
    <string>--block</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <!-- launchd's own PATH has no Homebrew: the folder `command -v node` prints must be on it -->
    <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/instruction-watch-codex.log</string>
  <key>StandardErrorPath</key><string>/tmp/instruction-watch-codex.log</string>
</dict>
</plist>
Shell
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/md.instruction.watch-codex.plist
launchctl print gui/$(id -u)/md.instruction.watch-codex | head   # is it running

Windows: a scheduled task at sign-in

PowerShell
$cli = (Get-Command instruction.cmd).Source
$action = New-ScheduledTaskAction -Execute $cli -Argument "watch instruction://acme/personal@latest --out `"$env:USERPROFILE\.codex\AGENTS.md`" --block"
$trigger = New-ScheduledTaskTrigger -AtLogOn
Register-ScheduledTask -TaskName "instruction.md watch (Codex)" -Action $action -Trigger $trigger

To see what it did: journalctl --user -u instruction-watch-codex.service (Linux) or /tmp/instruction-watch-codex.log (macOS). watch prints watching … when it starts and a line for each version it applies. On Windows, Get-ScheduledTaskInfo -TaskName "instruction.md watch (Codex)" says whether the task runs; the version is in the region's first line in AGENTS.md.

To stop it: systemctl --user disable --now instruction-watch-codex.service, launchctl bootout gui/$(id -u)/md.instruction.watch-codex, or Unregister-ScheduledTask -TaskName "instruction.md watch (Codex)". Your AGENTS.md keeps the last version written into it until you delete the region.

The MCP server

By default, Codex speaks MCP 2025-06-18. instruction.md's server speaks 2026-07-28 only and refuses older versions. So Codex connects through the instruction command's own stdio MCP server, which talks to instruction.md for it. This prints the settings:

Shell
instruction connect --host codex instruction://acme/support-agent@stable
config.toml
# ~/.codex/config.toml (or a trusted project's .codex/config.toml)
[mcp_servers.instruction-md]
command = "npx"
args = ["-y", "instruction.md", "mcp", "--follow", "instruction://acme/support-agent@stable", "--url", "https://instruction.md/mcp"]
# sign the bridge in once: npx -y instruction.md login
# then in a session: "read instruction://acme/support-agent@stable and follow it"
# to give every session this instruction, and a new version at the next prompt: npx -y @instruction.md/agents connect --host codex instruction://acme/support-agent@stable --with-hooks --write
# for your own instructions in every repository, live in Codex: npx -y instruction.md watch instruction://acme/support-agent@stable --out ~/.codex/AGENTS.md --block
  • The bridge serves the followed instruction as the resource instruction://current and the prompt follow. Signed in, it also serves instruction.md's tools on the same connection.
  • Sign the bridge in once with instruction login. For an agent, set INSTRUCTION_MD_TOKEN to a token minted with its agent credential (API key): instruction connect --host codex --agent <client id> <uri> prints that form.
  • Codex doesn't subscribe to resources, so the hooks or your AGENTS.md remain how a new version arrives.

As a skill

An instruction can also be a Codex skill: Codex lists it, and loads its text when the skill is used.

Shell
instruction agents install instruction://acme/support-agent@stable --host codex --as skill   # .agents/skills/support-agent/SKILL.md

Run it again to take a newer version. Codex notices the changed skill by itself. --name N names the skill's folder, --dir D writes into another project, and --force replaces a file the command didn't write.

In your own agent: the Codex SDK

@instruction.md/agents/agent reads the version a ref names and gives you its delivered text, the text a model receives. Hand it to the thread as its developer instructions:

TypeScript
import { Codex } from "@openai/codex-sdk";
import { follow } from "@instruction.md/agents/agent";

// a private instruction: INSTRUCTION_MD_TOKEN in the environment, or { token } here
const ins = await follow("instruction://acme/support-agent@stable", { requireSignature: true });
const codex = new Codex({ config: { developer_instructions: ins.text } });
const thread = codex.startThread();
await thread.run("Answer the open tickets");

follow() doesn't use the sign-in of instruction login. For a private instruction, it takes a token from INSTRUCTION_MD_TOKEN, or the token option (a string, or a function that returns one before each read). An agent's token comes from its agent credential (API key). Its other options are url, keys (the author keys accepted), refreshSeconds (60) and deadlineMs (5,000). It holds no live updates: each refresh is a read.

The text is set when the thread starts. A new version reaches the next thread you start: await ins.refresh() reads again and returns true when a new version came, and ins.text is then the new text. ins.close() closes its connection. Hooks in ~/.codex/hooks.json still apply to SDK threads.

The plugin

instruction.md's plugin carries the same hooks, the MCP server and a skill on working with followed instructions. It has a Codex manifest of its own, so Codex runs the same hooks. Install it from the marketplace at github.com/instruction-md/plugins:

Codex
codex plugin marketplace add instruction-md/plugins
codex plugin add instruction-md@instruction-md
# then approve its hooks once, in Codex: /hooks

The plugin's hooks run npx -y @instruction.md/agents hook auto, which tells Codex from Claude Code by the event it is sent. A project still names what it follows in .instruction/follow.json; a project without one is left alone. Use the plugin or the project's hooks, not both.

Who follows it, from where

Signed in, 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. For a whole organization, see Managed agents, which also prints the requirements.toml an administrator deploys to every machine.

Check it worked

Shell
instruction agents check --host codex

It says, each with its fix: whether you are signed in to instruction.md and which instruction (and version) the project follows, whether the servers and skills written here are the current version's, whether Codex is installed and signed in, and whether each server has an account on this machine. It exits 1 when something stops the agent.

Then start a new Codex session in the project and ask which instructions it follows. .instruction/current.md holds the text the hooks gave it.

Stop following

  • A project: remove the two @instruction.md/agents hook codex entries from .codex/hooks.json and delete .instruction/follow.json. Run instruction agents apply --host codex --remove first to take out the servers and skills it wrote.
  • Everywhere: stop watch (see above), then delete the region between the instruction.md:begin and instruction.md:end lines in ~/.codex/AGENTS.md.
  • The plugin: remove it in Codex.

If it doesn't work

What you see Why What to do
A session starts without the instruction Codex hasn't trusted the project or the hooks Trust the folder when Codex asks, then trust the hooks in /hooks
Codex asks to trust the hooks again A hook's command changed Trust them again; check the change in .codex/hooks.json
The first session times out on the hook npx downloads the package the first time, which can take longer than the 10-second timeout Run npm i -g @instruction.md/agents, then set up again with --cli instruction-agents
warning: …AGENTS.override.md is there: Codex reads it instead of …AGENTS.md Codex reads the override file first Delete or rename it, or write to it with --out
live updates are taken: … Still reading on schedule. Another agent or app has your plan's live updates Nothing breaks: watch reads every 60 seconds. See Live updates
A private instruction isn't read The hook or the bridge isn't signed in instruction login, then instruction agents check --host codex
Still stuck Ask us

Questions

Does the hook slow my prompts down?

Rarely. It reads the instruction at most every refreshSeconds (60 by default), and gives up after 1.5 seconds, using the last good copy. Between reads it answers from that copy. See How following works.

Can a project follow more than one instruction?

No. .instruction/follow.json names one instruction. To combine several, make one instruction that takes in the others with ::include or extends (Composition). Your own ~/.codex/AGENTS.md is separate, and can hold another one.

Does the instruction reach Codex in the IDE extension and codex exec?

Yes, wherever Codex runs the project's hooks: the CLI, the IDE extension, codex exec and the Codex SDK. Whether Codex cloud tasks run a repository's hooks is not verified.

Does a project's own AGENTS.md get in the way?

No. Codex reads it when a session starts, beside what the hook gives. If it says something different from the instruction, the model sees both. Move its rules into the instruction (Migrate rules files).

Last checked against the product:

Was this page helpful? Report a problem