Skip to main content
Run a Codex review on your uncommitted changes or compare a branch against a base ref. The review output is returned verbatim from Codex — the command will not apply any changes to your code.

​
Syntax

/codex:review [--wait|--background] [--base <ref>] [--scope auto|working-tree|branch]

​
Flags

​
--wait
boolean
Run the review in the foreground and wait for results before returning.
​
--background
boolean
Detach and run the review as a background job. Check progress with /codex:status.
​
--base
string
Compare against this git ref instead of the working tree. Accepts a branch name, tag, or commit hash — for example, main or a specific SHA.
​
--scope
string
Controls what is included in the review. Accepted values:
  • auto (default) — reviews the working tree if dirty, otherwise compares against the detected default branch
  • working-tree — always reviews uncommitted changes
  • branch — compares against the auto-detected default branch (main, master, or trunk)

​
Examples

/codex:review
/codex:review --base main
/codex:review --background

​
Execution behavior

If you pass neither --wait nor --background, the plugin estimates review size before asking:
  • It runs git status and git diff --shortstat to count changed files.
  • For branch reviews it uses git diff --shortstat <base>...HEAD.
  • If the change looks small — roughly 1–2 files — it recommends running in the foreground.
  • For everything else, including unclear size, it recommends background.
The plugin then asks once with two options, putting the recommended one first.
This command is read-only. It will not fix issues, apply patches, or make any changes to your code.
For multi-file changes, background mode is generally recommended. Start a review with --background, then check progress with /codex:status and retrieve the output with /codex:result.
For a review that challenges your design decisions rather than just implementation details, use /codex:adversarial-review. That command also supports extra focus text to steer the review toward specific risk areas.