# Codex Review Scope Options: auto, working-tree, and branch Explained

> Understand Codex review scope options auto, working-tree, and branch. Learn how each setting impacts your review process and choose the best one for your workflow.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-07-08

---

**The `--scope` parameter for Codex review commands accepts three values—`auto`, `working-tree`, and `branch`—that determine whether Codex examines uncommitted changes, a full branch diff, or automatically selects between the two based on repository state.**

The `openai/codex-plugin-cc` repository provides slash commands like `/codex:review` and `/codex:adversarial-review` that analyze Git changes using OpenAI's Codex model. These commands rely on the `--scope` flag to specify exactly which changes to include in the review, making it essential to understand how these scope options for reviews control the behavior of the plugin.

## The Three Scope Options Explained

### auto (Default)

When you omit the `--scope` flag, the plugin defaults to **auto** mode. In this mode, the plugin inspects the repository state to choose between `working-tree` and `branch`. If the working tree contains uncommitted changes, it selects `working-tree`; otherwise, it falls back to a `branch` diff against the default branch. This logic is implemented in the `resolveReviewTarget` function in `plugins/codex/scripts/lib/git.mjs` (lines 76-90).

### working-tree

The **working-tree** scope reviews all current uncommitted changes, including staged, unstaged, and untracked files. This mode executes `git diff` (both cached and non-cached) and includes any new files in the review. Use this scope when you want immediate feedback on work-in-progress before committing, regardless of branch history.

### branch

The **branch** scope reviews the diff between the current HEAD and a base reference. If you provide `--base <ref>`, the plugin uses that specific reference; otherwise, it auto-detects the repository's default branch (such as `main`, `master`, or `trunk`) via the `detectDefaultBranch` function. This scope is ideal for reviewing complete feature branches before merging.

## Source Code Implementation

The supported scope values are defined as a Set in `plugins/codex/scripts/lib/git.mjs` at lines 41-44:

```javascript
const supportedScopes = new Set(["auto", "working-tree", "branch"]);
…
if (!supportedScopes.has(requestedScope)) {
  throw new Error(
    `Unsupported review scope "${requestedScope}". Use one of: auto, working-tree, branch, or pass --base <ref>.`
  );
}

```

The command-line interface advertises these options in [`plugins/codex/commands/review.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/review.md) (line 3):

```yaml
argument-hint: '[--wait|--background] [--base <ref>] [--scope auto|working-tree|branch]'

```

## How Scope Affects Git Operations

The scope selection directly determines which Git commands the plugin executes to gather changes:

- **working-tree**: Runs `git diff --shortstat --cached`, `git diff --shortstat`, and `git status --short --untracked-files=all` to capture all local modifications.
- **branch**: Executes `git diff --shortstat <base>...HEAD` to measure changes between the current branch and the base reference.
- **auto**: Selects the appropriate measurement strategy based on whether `state.isDirty` returns true.

## Practical Usage Examples

Review current uncommitted changes:

```bash
/codex:review --scope working-tree

```

Review the entire branch against the default branch (auto-selects branch when the tree is clean):

```bash
/codex:review --scope auto

```

Review against a specific base reference:

```bash
/codex:review --base develop --scope branch

```

Run a background review of working tree changes:

```bash
/codex:review --scope working-tree --background

```

## Summary

- The `--scope` flag accepts three values: `auto`, `working-tree`, and `branch`.
- **auto** automatically chooses `working-tree` if uncommitted changes exist, otherwise uses `branch`.
- **working-tree** reviews staged, unstaged, and untracked files via `git diff` commands.
- **branch** reviews commits from the current HEAD to a base reference, defaulting to the repository's default branch.
- Validation occurs in `plugins/codex/scripts/lib/git.mjs`, which throws an error for unsupported scope values.

## Frequently Asked Questions

### What happens if I don't specify a scope?

If you omit the `--scope` flag, the plugin defaults to `auto` mode. According to the source code in `plugins/codex/scripts/lib/git.mjs`, the plugin checks `state.isDirty` to determine if uncommitted changes exist. If the working tree is dirty, it selects `working-tree`; otherwise, it falls back to `branch` mode against the detected default branch.

### Can I use scope options with adversarial reviews?

Yes. The `/codex:adversarial-review` command accepts the same `--scope` parameter as `/codex:review`. Both commands utilize the `resolveReviewTarget` function in `plugins/codex/scripts/lib/git.mjs` to determine which Git changes to examine, supporting `auto`, `working-tree`, and `branch` values.

### How does the plugin detect the default branch in branch mode?

When running with `--scope branch` without an explicit `--base` reference, the plugin calls the `detectDefaultBranch` function located in `plugins/codex/scripts/lib/git.mjs` (lines 94-115). This function identifies the repository's default branch by checking for common names like `main`, `master`, or `trunk`.

### What error occurs if I pass an invalid scope value?

The plugin validates the requested scope against a `supportedScopes` Set containing `"auto"`, `"working-tree"`, and `"branch"`. If you provide an unsupported value (such as `staged`), the code in `plugins/codex/scripts/lib/git.mjs` throws an Error stating: "Unsupported review scope [value]. Use one of: auto, working-tree, branch, or pass --base <ref>."