How to add a command approval rule in Codex

Codex command approval rules let a local session handle one command prefix differently from the wider approval policy. Use a rule when a repeated command should be allowed, prompted, or blocked in a predictable way while the rest of the session keeps its normal sandbox and approval boundary.

Rules live in .rules files under a rules/ directory next to an active Codex config layer. The user layer is ~/.codex/rules/, while a project layer uses .codex/rules/ and loads only when the project has been trusted. Each prefix_rule() matches the command argument list, not a sentence in a prompt.

Keep rule patterns narrow because the most restrictive matching decision wins across loaded files. Codex can split simple shell wrappers such as bash -lc "git status && gh pr view 7888" into separate commands before applying rules, but complex shell syntax is handled conservatively as the wrapper invocation itself.

1. Create the user rules directory.

   $ mkdir -p ~/.codex/rules

2. Open the default user rules file.

   $ vi ~/.codex/rules/default.rules

   Use .codex/rules/default.rules inside a trusted project only when the rule should travel with that repository instead of the user account.

3. Add a prefix_rule() for the command prefix.

   ~/.codex/rules/default.rules

   # Prompt before running GitHub PR reads outside the sandbox.
   prefix_rule(
       pattern = ["gh", "pr", "view"],
       decision = "prompt",
       justification = "Viewing pull requests requires approval because it can contact GitHub.",
       match = [
           "gh pr view 7888",
           "gh pr view --repo openai/codex",
       ],
       not_match = [
           "gh pr --repo openai/codex view 7888",
           "gh pr list",
       ],
   )

   Use decision = “allow” only for commands that may leave the sandbox without another prompt, decision = “prompt” when each match still needs review, and decision = “forbidden” when the command should be blocked without prompting.

4. Test a command that should match the rule.

   $ codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- gh pr view 7888
   {
     "matchedRules": [
       {
         "prefixRuleMatch": {
           "matchedPrefix": [
             "gh",
             "pr",
             "view"
           ],
           "decision": "prompt",
           "justification": "Viewing pull requests requires approval because it can contact GitHub."
         }
       }
     ],
     "decision": "prompt"
   }

   execpolicy check evaluates the rule file directly, so it can test rule behavior without opening a live Codex session.

5. Test a nearby command that should not match.

   $ codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- gh pr list
   {
     "matchedRules": []
   }

   No decision field means this rule file did not match the command. Normal approval policy and any other loaded rules still apply during a real session.

6. Restart Codex so normal sessions load the new rule.

   $ codex

   Already-running sessions keep the rules they loaded at startup.

   Related: How to start a Codex interactive session

7. Ask Codex to run the matching command when outside-sandbox access is needed.

   > Run gh pr view 7888 --json title,body

   The approval prompt should show the matching command prefix and the rule justification before the command runs outside the sandbox.