rules.md Codex Docs, 2026-04-23 12:28 UTC → 2026-05-13 00:57 UTC

6 6 

7## Create a rules file7## Create a rules file

8 8 

91. Create a `.rules` file under `./codex/rules/` (for example, `~/.codex/rules/default.rules`).91. Create a `.rules` file under a `rules/` folder next to an active config layer (for example, `~/.codex/rules/default.rules`).

102. Add a rule. This example prompts before allowing `gh pr view` to run outside the sandbox.102. Add a rule. This example prompts before allowing `gh pr view` to run outside the sandbox.

11 11 

12 ```python12 ```python

34 ],34 ],

35 )35 )

36 ```36 ```

37 

373. Restart Codex.383. Restart Codex.

38 39 

39Codex scans `rules/` under every [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config) location at startup. 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.40Codex scans `rules/` under every active config layer at startup, including [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config) locations and the user layer at `~/.codex/rules/`. Project-local rules under `<repo>/.codex/rules/` load only when the project `.codex/` layer is trusted.

41 

42When 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.

40 43 

41When Smart approvals are enabled (the default), Codex may propose a44When Smart approvals are enabled (the default), Codex may propose a

42`prefix_rule` for you during escalation requests. Review the suggested prefix45`prefix_rule` for you during escalation requests. Review the suggested prefix

56 - `allow`: Run the command outside the sandbox without prompting.59 - `allow`: Run the command outside the sandbox without prompting.

57 - `prompt`: Prompt before each matching invocation.60 - `prompt`: Prompt before each matching invocation.

58 - `forbidden`: Block the request without prompting.61 - `forbidden`: Block the request without prompting.

59- `justification` **(optional)**: A non-empty, human-readable reason for the rule. Codex may surface it in approval prompts or rejection messages. When you use `forbidden`, include a recommended alternative in the justification when appropriate (for example, `"Use \`rg` instead of `grep`.”`).62- `justification` **(optional)**: A non-empty, human-readable reason for the rule. Codex may surface it in approval prompts or rejection messages. When you use `forbidden`, include a recommended alternative in the justification when appropriate (for example, `"Use \`rg\` instead of \`grep\`."`).

60- `match` and `not_match` **(defaults to `[]`)**: Examples that Codex validates when it loads your rules. Use these to catch mistakes before a rule takes effect.63- `match` and `not_match` **(defaults to `[]`)**: Examples that Codex validates when it loads your rules. Use these to catch mistakes before a rule takes effect.

61 64 

62When Codex considers a command to run, it compares the command's argument list to `pattern`. Internally, Codex treats the command as a list of arguments (like what `execvp(3)` receives).65When Codex considers a command to run, it compares the command's argument list to `pattern`. Internally, Codex treats the command as a list of arguments (like what `execvp(3)` receives).