Allow native review targets to accept supplemental custom instructions

Open 💬 2 comments Opened May 11, 2026 by atwoodwang

What variant of Codex are you using?

CLI

What feature would you like to see?

I would like codex review / codex exec review to support combining native review targets with supplemental custom review instructions.

Today these modes are mutually exclusive:

codex exec review --base main "Use this plan as context..."
codex exec review --uncommitted "Focus on the acceptance criteria below..."
codex exec review --commit <sha> "Check whether this implements plan-N.md..."

They fail with errors like:

error: the argument '--base <BRANCH>' cannot be used with '[PROMPT]'

The desired behavior is not to replace the built-in reviewer prompt. The custom text should be additional review context/instructions while preserving the native Codex review behavior and diff targeting.

Possible CLI shapes:

codex exec review --base main --instructions "Review against this implementation plan: ..."
codex exec review --base main --instructions-file docs/superpowers/plans/foo-plan-1.md
codex exec review --uncommitted --instructions-file /tmp/review-context.md

or, if compatible with the existing UX:

codex exec review --base main "Supplemental review instructions..."

The important part is that the native target remains native (baseBranch, commit, uncommittedChanges) and the extra text is treated as supplemental review context.

Use case:

I am building automation around Codex review from another coding agent. The workflow is:

  1. A feature is planned in a design/plan document.
  2. Code is implemented on a feature branch.
  3. An orchestrator runs Codex as an independent reviewer.
  4. The orchestrator reads Codex's findings, applies or rebuts them, and loops until approval or a round cap.

For this to work well, I want to use Codex's native reviewer rather than reimplement code review with a generic codex exec prompt. The native reviewer appears to have better review-specific behavior and target handling. However, the review also needs per-invocation context, such as:

  • the implementation plan the branch is supposed to satisfy
  • acceptance criteria
  • non-goals and intentional tradeoffs
  • a requested output contract for automation, e.g. a final VERDICT: APPROVED / VERDICT: REVISE line
  • round-specific context in a review/fix/review loop

Current workarounds are weaker:

  • codex exec review --base main preserves native review targeting, but cannot receive plan/context.
  • codex exec review "custom instructions" preserves review mode, but loses native --base / --commit / --uncommitted targeting.
  • Plain codex exec with an inline git diff can be fully customized, but it no longer uses the native review target path and effectively reimplements review prompting.
  • Writing temporary instructions into AGENTS.md is too coarse-grained for per-review context and mutates repo/global state for what should be an ephemeral invocation.
  • Running native review first and then resume with context is possible, but it requires two turns and the first pass can be context-free.

The ideal behavior is a single native review invocation with both:

  1. deterministic native diff target selection, and
  2. supplemental caller-provided review context.

Additional information

I found #7825, but it is closed as not planned. I am opening this more specific request because the automation use case needs native target selection plus supplemental per-invocation context, not a full system prompt override.

Related issues:

  • #7825 requested prompt support with --base / --commit; it is closed as not planned, but the CLI still exposes [PROMPT] in help while rejecting it with scoped review flags.
  • #5598 asks for /review to use an issue summary / discussion context.
  • #10874 asks for custom review instructions in the Codex App.
  • #13163 asks for scriptable review -> fix -> review loops using the same built-in reviewer.
  • #6023 asks for more control over system prompts / reviewer behavior in exec workflows.

This request is narrower than system prompt customization. I am not asking to override the reviewer system prompt. I am asking for a native review target plus supplemental user instructions/context in the same invocation.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗