Skip to content
Lesson 4 of 757% of the course

Codex rules, hooks and AGENTS.md

Write Codex .rules for commands that are allowed, asked about or refused, test a command against them, add a hook to hooks.json and write AGENTS.md instructions, in Config Studio for Codex.

Config Studio for Codex courseIntermediate4 steps3 min
Open Config Studio for Codex
Nothing loads from YouTube until you press play. Then Google receives your IP address and may set its own storage. Narrated with an AI-generated voice. Privacy

The sandbox decides where commands may write. Rules decide which commands may run outside it without asking, hooks run your own code at points in a session, and AGENTS.md tells Codex how you work. This lesson sets up all three and tests the rules before Codex ever sees them.

Write rules for commands

Open Config Studio for Codex and press Rules (.rules files). Under Rules, write one rule a line: the decision, the command prefix, then -- and why.

prompt git push -- Pushing leaves this machine
forbidden rm -rf -- Delete with a narrower path
allow npm test
  • allow runs without asking.
  • prompt asks you every time.
  • forbidden refuses the command.

Write a|b at one position for either word: allow gh pr view|list allows both commands, and the file gets them as a list Codex reads the same way.

Three buttons add a set at once: Ask before publishing, Refuse the destructive ones and Tests run without asking. Which rules file chooses yours (~/.codex/rules/default.rules) or the repository's (.codex/rules/default.rules, read in a trusted project).

One line each, written as prefix_rule() calls.

The right column shows the file Codex reads, one prefix_rule() a rule, each with a match example so Codex checks the rule when it loads.

Test a command

Press Try it at the top and pick Would Codex run this command? Paste your rules under Rules and a command under Command, for example git add . && rm -rf build. The answer says allowed, asked or refused, and which rule decided.

A chain is checked command by command; the strictest answer wins.

A chain joined with &&, ||, ; or | is checked command by command, the way Codex splits it, and the strictest answer wins. On your machine, codex execpolicy check gives the same answer from the real files.

Add a hook

Back on Configure, press Hooks. A hook runs a command (or a tool of an MCP server) at one point in a session:

  1. Which hooks.json: yours in ~/.codex, or the repository's in .codex.
  2. When it runs: PreToolUse before a tool runs, Stop when Codex is about to stop, SessionStart, and nine more.
  3. Matcher: a regex on the tool name, such as ^Bash$. Empty matches every tool.
  4. Command: what runs. It reads the event as JSON on stdin; exit 2 blocks, with the reason on stderr.

The grey text in each field is an example. Type your own, or press Fill in the example on the right to start from it.

One hook: when it runs, what it matches and what it runs.

A hook does not run until you trust it: type /hooks in Codex to review and trust it, and again after any change.

Write standing instructions

Press AGENTS.md. Who this applies to picks you in every project (~/.codex/AGENTS.md) or the repository (./AGENTS.md). Write The instructions in Markdown: short, because Codex reads every line on every turn.

Write it as AGENTS.override.md writes a file Codex reads instead of AGENTS.md at the same level, for a temporary change you undo by deleting one file. In a repository, Codex joins the files from the root down to your folder, so the nearest one counts most.

Next: customise the Codex status line, the footer under the prompt and the terminal title.

Your progress stays in this browser only.
Contact