How to add a command approval rule in Codex

Commands that read remote services can still expose private project data. A Codex command approval rule can require review before a particular command prefix runs outside the sandbox, without changing the session's broader approval policy.

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's .codex/rules/ loads only when its configuration layer is trusted. An explicit CODEX_HOME replaces the default user configuration directory.

A prefix matches command arguments in order, so moving an option before a subcommand can put a command outside that rule's scope. Rules complement the sandbox rather than defining a complete access boundary. An interactive Codex CLI session with a working model provider is required to confirm the approval behavior.

1. Create the rules directory under the active Codex user configuration directory.

   $ mkdir -p "${CODEX_HOME:-$HOME/.codex}/rules"

   Without an explicit CODEX_HOME, this is ~/.codex/rules. With one, the directory is $CODEX_HOME/rules.

2. Open ~/.codex/rules/default.rules in your text editor.

   If CODEX_HOME is set, open $CODEX_HOME/rules/default.rules instead. If the file does not exist, create it at that exact path. Existing contents must remain intact.

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

3. Append the following rule at the end of the active default.rules file if gh pr view has no existing rule.

   An allow decision can let matching commands run outside the sandbox without another prompt. A narrow prompt rule keeps human approval in the path; a broad prefix such as gh would also affect unrelated GitHub commands.

   # 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",
       ],
   )

   If that prefix already has a rule, keep its existing decision instead of adding a duplicate. Surrounding rules remain unchanged. The most restrictive matching decision wins, in the order forbidden, prompt, then allow. The optional match and not_match examples are checked when the file loads. A syntax error must be fixed before restarting Codex. Removing only this added rule and restarting Codex reverses the change.

   Codex can split simple shell wrappers into individual commands before applying rules. Complex shell syntax can instead be evaluated as the wrapper invocation, so a prefix rule is not a substitute for the sandbox.
   Related: OpenAI rules documentation

4. Save the active default.rules file in your editor.
5. Test a command that should match the rule.

   $ codex execpolicy check --pretty --rules "${CODEX_HOME:-$HOME/.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 without running gh. The expected decision is prompt. Other existing rules can add matches or produce a stricter decision.

6. Start a fresh Codex session with workspace-write sandboxing and on-request approvals.

   $ codex --sandbox workspace-write --ask-for-approval on-request

   Already-running sessions keep their loaded rules. These launch flags permit ordinary sandboxed commands while retaining requests for wider access. Manual approval review is the default; automatic approval review can handle requests without displaying a dialog. A trusted project directory with familiar contents is an appropriate starting location.
   Related: How to start a Codex interactive session

7. Request the matching command once.

   Approving the request permits gh to contact GitHub. Canceling it needs no GitHub sign-in and leaves the pull request unread.

   > Use the terminal to run gh pr view 7888 --json title,body exactly once. Do not retry if permission is denied.

   The approval dialog names the requested command. Codex may also show the rule's justification; its presence identifies the matching rule. The checker result confirms the prefix decision when the dialog omits that optional text.

8. Reject the matching request with Esc.

   ✗ You canceled the request to run gh pr view 7888 --json title,body

   The cancellation confirms that approval was withheld before execution. The rule remains saved for later sessions. A missing dialog needs investigation of rule loading and the active approval settings before relying on this boundary.