/codex:review

Run a read-only Codex code review against your current git state.

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.

Related

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.