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 ↗

2 Comments

hieu-lee · 3 months ago

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 --help advertises a positional prompt:

Usage: codex review [OPTIONS] [PROMPT]

Arguments:
  [PROMPT]
          Custom review instructions. If `-` is used, read from stdin

But passing a prompt with a native target is rejected before review starts:

$ codex review --uncommitted "focus on panic paths"
error: the argument '--uncommitted' cannot be used with '[PROMPT]'

Usage: codex review --uncommitted [PROMPT]

For more information, try '--help'.
exit=2

I also added a focused local parser test to capture the expected behavior implied by the help text:

#[test]
fn review_uncommitted_accepts_supplemental_prompt() {
    let cli = MultitoolCli::try_parse_from([
        "codex",
        "review",
        "--uncommitted",
        "focus on panic paths",
    ])
    .expect("review help advertises [PROMPT] with --uncommitted");

    let Some(Subcommand::Review(ReviewCommand { args, .. })) = cli.subcommand else {
        panic!("expected review subcommand");
    };

    assert!(args.uncommitted);
    assert_eq!(args.prompt.as_deref(), Some("focus on panic paths"));
}

Running it fails with the same root parser issue:

$ just test -p codex-cli review_uncommitted_accepts_supplemental_prompt
TRY 1 FAIL codex-cli::bin/codex tests::review_uncommitted_accepts_supplemental_prompt
...
review help advertises [PROMPT] with --uncommitted: ErrorInner { kind: ArgumentConflict, context: ... InvalidArg "--uncommitted", PriorArg "[PROMPT]", Usage "codex review --uncommitted [PROMPT]" ... }
Summary: 0 passed, 1 failed

Likely source: codex-rs/exec/src/cli.rs defines ReviewArgs with conflicts_with_all = ["base", "commit", "prompt"] on --uncommitted and similar prompt conflicts 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.

ictechgy · 1 month ago

I can still reproduce this on current CLI codex-cli 0.142.5 on 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:

codex review --base main 'custom review instructions'
codex exec review --base main 'custom review instructions'
codex review --uncommitted 'custom review instructions'
codex exec review --uncommitted 'custom review instructions'
codex review --commit HEAD 'custom review instructions'

Observed examples:

$ codex review --base main 'custom review instructions'
rc=2
error: the argument '--base <BRANCH>' cannot be used with '[PROMPT]'

Usage: codex review --base <BRANCH> [PROMPT]
$ codex exec review --base main 'custom review instructions'
rc=2
error: the argument '--base <BRANCH>' cannot be used with '[PROMPT]'

Usage: codex exec review --base <BRANCH> [PROMPT]
$ codex review --uncommitted 'custom review instructions'
rc=2
error: the argument '--uncommitted' cannot be used with '[PROMPT]'

Usage: codex review --uncommitted [PROMPT]
$ codex review --commit HEAD 'custom review instructions'
rc=2
error: the argument '--commit <SHA>' cannot be used with '[PROMPT]'

Usage: codex review --commit <SHA> [PROMPT]

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:

  1. allow supplemental instructions with native review targets, matching the current help text;
  2. add an explicit option such as --instructions / --instructions-file; or
  3. update the help/usage text to clearly state that prompts are not supported with native target flags.