> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/openai/codex-plugin-cc/llms.txt
> Use this file to discover all available pages before exploring further.

# /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

<ParamField path="--wait" type="boolean">
  Run the review in the foreground and wait for results before returning.
</ParamField>

<ParamField path="--background" type="boolean">
  Detach and run the review as a background job. Check progress with `/codex:status`.
</ParamField>

<ParamField path="--base" type="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.
</ParamField>

<ParamField path="--scope" type="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`)
</ParamField>

## Examples

```bash theme={null}
/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.

<Note>
  This command is read-only. It will not fix issues, apply patches, or make any changes to your code.
</Note>

<Tip>
  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`.
</Tip>

## Related

For a review that challenges your design decisions rather than just implementation details, use [/codex:adversarial-review](/commands/adversarial-review). That command also supports extra focus text to steer the review toward specific risk areas.