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

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:

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 (line 3):

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:

/codex:review --scope working-tree

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

/codex:review --scope auto

Review against a specific base reference:

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

Run a background review of working tree changes:

/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 ."

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}