Allow native review targets to accept supplemental custom instructions
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:
- A feature is planned in a design/plan document.
- Code is implemented on a feature branch.
- An orchestrator runs Codex as an independent reviewer.
- 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: REVISEline - round-specific context in a review/fix/review loop
Current workarounds are weaker:
codex exec review --base mainpreserves native review targeting, but cannot receive plan/context.codex exec review "custom instructions"preserves review mode, but loses native--base/--commit/--uncommittedtargeting.- Plain
codex execwith an inlinegit diffcan be fully customized, but it no longer uses the native review target path and effectively reimplements review prompting. - Writing temporary instructions into
AGENTS.mdis 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
resumewith 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:
- deterministic native diff target selection, and
- 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
/reviewto 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.
2 Comments
I can reproduce this as a CLI parser/help consistency bug on current CLI
0.133.0(Darwin 25.4.0 arm64 arm).codex review --helpadvertises a positional prompt:But passing a prompt with a native target is rejected before review starts:
I also added a focused local parser test to capture the expected behavior implied by the help text:
Running it fails with the same root parser issue:
Likely source:
codex-rs/exec/src/cli.rsdefinesReviewArgswithconflicts_with_all = ["base", "commit", "prompt"]on--uncommittedand similarpromptconflicts on--base/--commit. That makes the prompt impossible to use with native targets even though generated help/error usage still exposes[PROMPT].If supplemental prompts are intended, the parser conflict should be removed and the prompt should be threaded as additional review context while preserving the native target. If they are not intended, the help/error usage should stop advertising
[PROMPT]alongside native review targets.I can still reproduce this on current CLI
codex-cli 0.142.5on macOS/Darwin arm64.The current help/usage text still appears self-contradictory: it advertises
[PROMPT]together with native review targets, but the parser rejects that combination before any model call is made.Minimal repro in a temporary git repo:
Observed examples:
Why this matters for automation: an orchestrator currently has to choose between native Codex review targeting (
--base,--commit,--uncommitted) and per-run supplemental instructions such as acceptance criteria, non-goals, round context, or a machine-readable verdict contract. It cannot use both in one native review invocation.Any of these outcomes would resolve the ambiguity:
--instructions/--instructions-file; or