Files
dev/docs/execpolicy.md
T
zeekayandHanzo Dev 6cbbea2d03 merge: just-every/code v0.6.169 (e4fe007150) — keep Hanzo identity
Our history is just-every's with author emails rewritten, so the graphs are
disjoint and git finds no merge base. Supplied one by hand: d1f1f51a41, the
just-every commit matching our Oct-2025 fork point (22 files apart). 9618
upstream commits, 7004 files, +1.81M/-159k, 37 conflicts.

Resolution:
- Upstream code where our side was the Oct-2025 prototype of a feature they
  have since reimplemented 3-5x larger (agent_runs, browser_sessions,
  history_cell/{agent,browser}, the vt100 harness and its snapshots).
- Upstream's config.rs module split (builder/defaults/sources/validation)
  kept; zen5-coder and the provider-follows-model rule re-applied on top.
- Ours where the file IS the identity: README, package.json, postinstall,
  release notes pipeline, integration-zed.
- Hybrid where upstream improved a file we had branded: updates.rs (their
  release-repo migration, our hanzoai/dev), release.yml (their fail-fast npm
  auth check, our package name), chatwidget.rs (their turn handling, our
  HANZO_USER_KEY hint), exec human output (their 237 lines, our banner).

Superseded and dropped deliberately: our resume_command_name() coder-alias
hack — upstream's derive_resume_command_name() reads the invocation basename
generically, which yields "dev" for us.

LLM.md now records the real topology and the sync point; AGENTS.md and
CLAUDE.md are symlinks to it again. Single parent on purpose: adopting
jecode/main as a second parent would re-import 13,742 commits carrying the
upstream author emails a prior rewrite deliberately removed.

Version 0.2.188 -> 0.2.189.

Co-authored-by: Hanzo Dev <[email protected]>
2026-08-05 23:09:12 -07:00

2.9 KiB

Execution policy

Every Code can enforce your own rules-based execution policy before it runs shell commands. Policies live in Starlark .codexpolicy files under ~/.code/policy (Code still reads ~/.codex/policy for backward compatibility).

How to create and edit rules

TUI interactions

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

Screenshot 2025-12-04 at 9 23 54 AM

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

  1. Create a policy directory: mkdir -p ~/.code/policy.
  2. Add one or more .codexpolicy files in that folder. Code automatically loads every .codexpolicy file in there on startup.
  3. 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; Code picks the strictest decision when multiple rules match (forbidden > prompt > allow).
  • match and not_match act as optional unit tests. Code validates them when it loads your policy, so you get feedback if an example has unexpected behavior.

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

Preview decisions

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

code execpolicy check --policy ~/.code/policy/default.codexpolicy git push origin main

Pass multiple --policy flags to test how several files combine, and use --pretty for formatted JSON output. See the code-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.