mirror of https://github.com/openai/codex.git synced 2026-02-01 22:47:52 +00:00

Files

Michael Bolin e0d7ac51d3 fix: policy/*.codexpolicy -> rules/*.rules (#7888 )

We decided that `*.rules` is a more fitting (and concise) file extension
than `*.codexpolicy`, so we are changing the file extension for the
"execpolicy" effort. We are also changing the subfolder of `$CODEX_HOME`
from `policy` to `rules` to match.

This PR updates the in-repo docs and we will update the public docs once
the next CLI release goes out.

Locally, I created `~/.codex/rules/default.rules` with the following
contents:

```
prefix_rule(pattern=["gh", "pr", "view"])
```

And then I asked Codex to run:

```
gh pr view 7888 --json title,body,comments
```

and it was able to!

2025-12-11 14:46:00 -08:00

2.8 KiB

Raw Blame History

Execpolicy quickstart

Codex can enforce your own rules-based execution policy before it runs shell commands. Policies live in .rules files under ~/.codex/rules.

How to create and edit rules

TUI interactions

Codex CLI will present the option to whitelist commands when a command causes a prompt.

Whitelisted commands will no longer require your permission to run in current and subsequent sessions.

Under the hood, when you approve and whitelist a command, codex will edit ~/.codex/rules/default.rules.

Editing `.rules` files

Create a policy directory: mkdir -p ~/.codex/rules.
Add one or more .rules files in that folder. Codex automatically loads every .rules file in there on startup.
Write prefix_rule entries to describe the commands you want to allow, prompt, or block:

prefix_rule(
    pattern = ["git", ["push", "fetch"]],
    decision = "prompt",  # allow | prompt | forbidden
    match = [["git", "push", "origin", "main"]],  # examples that must match
    not_match = [["git", "status"]],              # examples that must not match
)

pattern is a list of shell tokens, evaluated from left to right; wrap tokens in a nested list to express alternatives (for example, match both push and fetch).
decision sets the severity; Codex picks the strictest decision when multiple rules match (forbidden > prompt > allow).
match and not_match act as optional unit tests. Codex validates them when it loads your policy, so you get feedback if an example has unexpected behavior.

In this example rule, if Codex wants to run commands with the prefix git push or git fetch, it will first ask for user approval.

Preview decisions

Use the codex execpolicy check subcommand to preview decisions before you save a rule (see the codex-execpolicy README for syntax details):

codex execpolicy check --rules ~/.codex/rules/default.rules git push origin main

Pass multiple --rules flags to test how several files combine, and use --pretty for formatted JSON output. See the codex-rs/execpolicy README for a more detailed walkthrough of the available syntax.

Example output when a rule matches:

{
  "matchedRules": [
    {
      "prefixRuleMatch": {
        "matchedPrefix": ["git", "push"],
        "decision": "prompt"
      }
    }
  ],
  "decision": "prompt"
}

When no rules match, matchedRules is an empty array and decision is omitted.

{
  "matchedRules": []
}

Status

execpolicy commands are still in preview. The API may have breaking changes in the future.

2.8 KiB Raw Blame History