Codex CLI as Reviewer: Read-Only Verdict Workflows

The review contract

A review is not a coding task with the word "review" in the prompt. It has three properties:

• No writes. The reviewer reads the diff and the surrounding code; it does not edit, stage, or commit.
• A target. Uncommitted changes, a base branch, a single commit, or a custom instruction set.
• A verdict shape. Findings ranked by severity, each tied to a file and a triggering input.

Codex has a mode for the first two and a separate mechanism for the third.

Read-only configuration

For local changes, use review mode rather than an editing session:

codex review --uncommitted
codex review --base main
codex review --commit <sha>

Choose exactly one target, or pass custom instructions as a prompt. --title is only valid with --commit. Review reports prioritized findings without modifying your working tree, which is the property that makes it safe to run against someone else's branch.

Inside the TUI, /review starts the same workflow and lets you choose a base branch or uncommitted changes. review_model in config.toml overrides the model used by /review; it defaults to the session model. A cheaper reviewer model is a reasonable default when the builder already used the expensive one.

When you need the reviewer to be a script rather than a session, use codex exec with the read-only sandbox:

codex exec --sandbox read-only --ask-for-approval never \
  "Review the diff between HEAD and origin/main. Report only defects that change behavior. Do not edit files."

codex exec runs read-only by default, but set the sandbox explicitly. Explicit configuration survives edits to defaults and reads correctly in a pipeline review.

A verdict instead of prose

Free-form review text is hard to gate on. Constrain the final message with a JSON Schema:

{
  "type": "object",
  "properties": {
    "verdict": { "enum": ["pass", "pass_with_findings", "block"] },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "severity": { "enum": ["critical", "high", "medium", "low"] },
          "file": { "type": "string" },
          "line": { "type": "integer" },
          "issue": { "type": "string" },
          "triggering_input": { "type": "string" },
          "suggested_fix": { "type": "string" }
        },
        "required": ["severity", "file", "issue", "triggering_input"]
      }
    }
  },
  "required": ["verdict", "findings"],
  "additionalProperties": false
}

codex exec --sandbox read-only --ask-for-approval never \
  --output-schema ./review.schema.json -o ./review.json \
  "Review the current diff against main using review.schema.json. A finding requires a concrete input that triggers it. If you cannot name the input, drop the finding."

The output lands in review.json and on stdout. A pipeline can block on verdict, and a human can read the findings without parsing markdown.

TODO: capture from real run — paste one completed review.json from a real diff, with the verdict and one finding.

Wiring it to a builder agent

The pattern is builder writes, reviewer reads, builder responds. Keep the roles in separate sessions so the reviewer's context is the diff rather than the reasoning that produced it.

1. The builder works in workspace-write and stops after a bounded change.
2. The reviewer runs codex review --uncommitted or the read-only codex exec above.
3. Findings go back to the builder as a numbered list, each with file and triggering input.
4. The builder fixes one finding per turn and reruns the narrow test.
5. The reviewer reruns on the updated diff. A second pass that only re-reports fixed items is a signal that the verdict schema is too loose.

This is the same shape as Claude Code's opencode auditors pattern with the roles reversed: one model builds, another reviews, and neither shares a session. If the diff includes untrusted input, the review prompt itself needs injection hygiene — see prompt injection defense.

What to review first

A review that starts with style will spend its budget before it reaches the part that matters. Order the pass:

1. Behavior changes — status codes, response shapes, default values, and anything a client can observe.
2. Data loss and security boundaries — deletes, overwrites, auth checks, and anything that writes outside the workspace.
3. Failure paths — what happens on empty input, a timeout, a duplicate request.
4. Test gaps — the rejected input that has no test, not the missing assertion on a mock.
5. Maintainability — naming, duplication, and structure, last.

Put that order in the prompt or in review_model instructions, or the reviewer will default to whatever it notices first.

Failure modes

• Reviewing the summary instead of the diff. Point the reviewer at git diff output or a base ref, not at the builder's description of its work.
• Findings without triggers. "Error handling is weak" cannot be verified. Require the input that produces the failure.
• Severity inflation. Without a rubric, everything becomes critical. Define the levels in the prompt: critical means data loss or a security boundary, high means a user-visible failure on a normal path.
• Reviewer writes. A reviewer that edits files removes the separation the workflow depends on. Keep the sandbox read-only and the prompt explicit.
• Gating on a model's opinion. The verdict is evidence for a human decision, not a replacement for tests. Run the tests the reviewer cites.

The same workflow runs with an OpenCode builder in place of Claude Code; the tool comparison covers the cost and context differences that affect how often you can afford a review pass. For the prompt-side mechanics of constraining a reviewer, see tool-use patterns.

Sources

• Code review
• Non-interactive mode
• Developer commands
• Agent approvals and security