MemoryLake
Back to all articles
TutorialNovember 17, 2026·10 min read

What Do Codex Rules Control? Why a .rules File Isn't Where Instructions Go, Where Always-Allow Approvals Get Saved, and Which Decision Wins When Rules Overlap (2026)

You wanted Codex to follow your team's conventions, so you searched for a Codex rules file, created a rules/ folder, and wrote your style guide into it. Nothing changed. A few weeks earlier, you had told Codex to always allow npm test, and it hasn't asked since, but you couldn't say where that choice was saved.

Both have the same explanation. In Codex, rules aren't instructions. OpenAI's documentation opens with a single sentence: "Use rules to control which commands Codex can run outside the sandbox." And when you approve a command for good, that approval is saved as a rule.

This guide covers what Codex rules are, where conventions belong instead, where rules files live and when they load, where always-allow approvals get saved, how a rule is written, which decision wins when rules overlap, how shell scripts are checked, and how to test your rules.

What Codex rules are

Codex runs commands in a sandbox. Rules decide what happens when a command needs to run outside it: run it, ask you first, or refuse.

OpenAI's documentation adds a caveat at the top: "Rules are experimental and may change."

Rules are written in a .rules file. The documentation says the format uses Starlark, which has syntax like Python but is "designed to be safe to run: the rules engine can run it without side effects (for example, touching the filesystem)."

So a rules file is a small program of command policies. Prose written into it isn't a rule, and it won't change how Codex writes code.

Where your conventions go instead

Coding conventions, project structure, and team guidance belong in AGENTS.md. OpenAI's documentation on memories is direct about this: "Keep required team guidance in AGENTS.md or checked-in documentation."

The same page warns against relying on memory for rules that must always apply: "Treat memories as a helpful recall layer, not as the only source for rules that must always apply."

That gives you three different places with three different jobs:

  • AGENTS.md: what Codex should know and how it should work in your project.
  • Memories: useful context Codex carries forward from earlier chats.
  • Rules: which commands can run outside the sandbox, and how.

If Codex isn't following instructions you've written in AGENTS.md, rules aren't the place to look. Check which instruction files loaded. We covered how to check that in our guide to stopping Codex from skipping AGENTS.md rules.

Where rules files live and when they load

You create a .rules file under a rules/ folder next to an active config layer. The documentation's example is ~/.codex/rules/default.rules.

Then: "Codex scans rules/ under every active config layer at startup". That includes Team Config locations and your user layer at ~/.codex/rules/.

Two details decide whether a rule takes effect:

  • Restart after editing. The documentation's steps end with restarting Codex, because rules are scanned at startup.
  • Project rules need trust. "Project-local rules under <repo>/.codex/rules/ load only when the project .codex/ layer is trusted."

So a rule committed to a repository won't apply on a teammate's machine until they've trusted that project.

Where always-allow approvals get saved

This part is easy to miss, and it's a kind of memory.

The documentation says: "When you add a command to the allow list in the TUI, Codex writes to the user layer at ~/.codex/rules/default.rules so future runs can skip the prompt."

Three things follow from that sentence:

  • Your approvals are written down. They're rules in a file, not a setting hidden in a session.
  • They're in the user layer. They're saved in your home directory, not in the project you were working in when you approved.
  • You can read and edit them. Open ~/.codex/rules/default.rules to see every command you've allowed this way.

There's a second way rules get added. "When Smart approvals are enabled (the default), Codex may propose a prefix_rule for you during escalation requests." The documentation adds a caution: "Review the suggested prefix carefully before accepting it."

The reason is the prefix. A suggested rule matches every command that starts with that prefix, so a short prefix can allow much more than the one command you meant to approve.

How a rule is written

Each rule is a prefix_rule() with a few fields. The documentation describes them:

  • pattern is required. It's a list that defines the command prefix to match, such as the three words gh, pr, and view. Each element can be a literal, or a set of alternatives at that position.
  • decision defaults to allow. The options are allow, prompt, and forbidden.
  • justification is optional: "A non-empty, human-readable reason for the rule." The documentation says Codex may show it in approval prompts or rejection messages.
  • match and not_match are optional examples "that Codex validates when it loads your rules." The documentation calls them inline unit tests.

The documentation's guidance on forbidden rules is worth following: "When you use forbidden, include a recommended alternative in the justification when appropriate". That way, when Codex hits the rule, it learns what to do instead.

The justification field is also the closest thing a rule has to a reason. A year later, it's what tells you why a command was blocked.

What the documentation's example rule does

OpenAI's example is a useful template. It's a single rule for viewing pull requests with the GitHub CLI.

  • The pattern is the prefix made of gh, pr, and view.
  • The decision is prompt, so Codex asks before each matching command runs outside the sandbox.
  • The justification reads "Viewing PRs is allowed with approval", which is what you'd see in the prompt.
  • The match examples include viewing a PR by number and with extra flags, so Codex checks that the rule covers them.
  • The not_match example puts the repository flag before the word view, and the comment explains why it shouldn't match: "Does not match because the pattern must be an exact prefix."

That last example shows how literal matching is. A command with the same words in a different order is a different prefix, so it needs its own rule.

Which decision wins when rules overlap

Rules from several layers can match the same command. The documentation is explicit about the outcome: "Codex applies the most restrictive decision when more than one rule matches (forbidden > prompt > allow)."

So an allow in your user layer can't loosen a forbidden rule from another layer. The most restrictive matching decision applies.

Admins can use this deliberately. The documentation says admins "can also enforce restrictive prefix_rule entries" from the managed requirements.toml file.

How shell scripts are checked

Some tools wrap several commands into one invocation, such as a bash -lc call running a short script. The documentation explains why that matters: such a command "can hide more than one action inside one string".

Codex handles this in two ways.

When it can safely split the script. If the script is a simple chain of plain commands joined by operators like &&, ||, ;, or |, Codex parses it and splits it into separate commands. "Codex then evaluates each command against your rules, and the most restrictive result wins." The documentation's example: allowing git add doesn't allow a chained rm -rf hidden after it, because that part is evaluated separately.

When it can't. If the script uses redirection, substitutions, environment variables, wildcards, or control flow, Codex doesn't try to interpret it. The whole invocation is treated as a single command, and your rules apply to that.

The documentation sums up the design: "you get the security of per-command evaluation when it's safe to do so, and conservative behavior when it isn't."

How to test a rule

Before you rely on a rule, check it. The documentation says to use codex execpolicy check, pointing it at a rules file and giving it a command. "The command emits JSON showing the strictest decision and any matching rules, including any justification values from matched rules." You can pass more than one rules file to see how they combine.

The match and not_match examples inside a rule do a similar job automatically, since Codex validates them when it loads your rules.

Rules and the retired untrusted policy

If you used the old untrusted approval policy, rules matter more now. OpenAI's approvals documentation says Codex no longer supports that setting and explains how to keep a strict project. You add a project entry with an untrusted trust level to your user-level config, and then: "Commands then require approval unless an execution-policy rule allows them."

In that setup, your allow rules are the only way a command runs without asking. That's another reason to keep default.rules tidy.

Codex has a similar trust step for hooks, which need review before they run. We covered it in our guide to why Codex hooks need review.

What people try first

Writing conventions into a rules file. Rules control commands. Conventions go in AGENTS.md.

Editing a rule and expecting it to apply right away. Rules are scanned at startup.

Committing project rules and expecting them everywhere. Project rules load only when the project layer is trusted.

Accepting a suggested prefix without reading it. A short prefix can allow more than you meant.

Allowing a command to override a block. The most restrictive decision wins.

The Fix: Put each kind of instruction where it belongs

Step 1: Move conventions to AGENTS.md

Take anything that describes how to write code out of rules files and into AGENTS.md.

Step 2: Review your saved approvals

Open ~/.codex/rules/default.rules and remove allow rules you no longer need.

Step 3: Add justifications and examples

Give each rule a justification, and add match and not_match examples so mistakes show up when Codex loads it.

Step 4: Record why each command policy exists

Write down the decisions behind your rules, such as why a command is blocked or which alternative to use.

Setting this up in MemoryLake

A rules file records what Codex may run. The decisions behind it, such as why deploy commands are blocked locally or which test command replaced an old one, are project knowledge that every assistant on the project should have.

MemoryLake is a memory layer for that kind of project context, such as decisions, conventions, and the reasons behind your safeguards, kept in one place you maintain and available to the assistants you connect, such as ChatGPT, Claude Code, and Codex.

You write the entries yourself, in your own words. Nothing is read out of, written to, or deleted from your .rules files, your AGENTS.md files, your Codex config or memories, your sessions, or any vendor's store. Codex rules and approvals work the way OpenAI describes them.

Step 1: Create an API key

Sign in and generate a key from the dashboard. Store it outside your repositories, like any other credential.

The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent
The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent

Step 2: Upload your first memories

Start with what you wrote in Step 4 of the fix: the reasons behind your command policies and the alternatives to blocked commands. One decision per entry.

The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory
The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory

Step 3: Connect your AI & agents

Connect Codex, Claude Code, and the other assistants you use. Each can draw on the same decisions, whatever its own permission system.

The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer
The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer

What this changes in practice

The first difference is clarity. Rules stay about commands, and reasons live where people can read them.

The second is consistency across tools. Claude Code has its own permission rules, and the decisions behind both can live in one place.

The third is easier review. A teammate can see why a rule exists before changing it.

Best practices for Codex rules

Use rules for commands only. Conventions belong in AGENTS.md.

Check your user layer. Always-allow approvals are saved in ~/.codex/rules/default.rules.

Read suggested prefixes. They can match more than one command.

Write justifications. Include an alternative for forbidden rules.

Add match examples. Codex validates them when it loads rules.

Test with codex execpolicy check. See the strictest decision before relying on it.

Restart after edits. Rules are scanned at startup.

Conclusion

Codex rules control which commands can run outside the sandbox: allow, prompt, or forbidden. They aren't instructions, and conventions belong in AGENTS.md. Rules files live in a rules/ folder next to each config layer, load at startup, and project rules need a trusted project. When you allow a command in the TUI, Codex saves it to ~/.codex/rules/default.rules in your user layer.

When rules overlap, the most restrictive decision wins, and simple shell scripts are split so each command is checked on its own. Review your saved approvals, add justifications, and keep the reasons behind your rules somewhere you maintain.

Frequently asked questions

What are Codex rules?

Policies that control which commands Codex can run outside the sandbox, written in .rules files.

Can I put coding instructions in a Codex rules file?

No. Rules control commands. OpenAI says to keep team guidance in AGENTS.md or checked-in documentation.

Where does Codex save always-allow approvals?

In the user layer at ~/.codex/rules/default.rules.

Which rule wins if two match?

The most restrictive: forbidden, then prompt, then allow.

Why isn't my project's rule working?

Project rules load only when the project .codex/ layer is trusted, and rules are scanned at startup.

How do I test a Codex rule?

Run codex execpolicy check with a rules file and a command. It shows the strictest decision and matching rules.

Are Codex rules stable?

OpenAI says rules are experimental and may change.