How Codex Resolves Review Targets: Working-Tree vs Branch Detection

Codex resolves review targets by evaluating explicit CLI flags (--base or --scope) before falling back to automatic detection, selecting working-tree mode when uncommitted changes exist and branch mode when the repository is clean.

The openai/codex-plugin-cc repository implements intelligent target resolution through the resolveReviewTarget function located in plugins/codex/scripts/lib/git.mjs. This logic determines whether codex review analyzes your current working directory changes or compares your HEAD against a base branch, adapting automatically to repository state while respecting explicit user overrides.

Priority-Based Resolution Logic in resolveReviewTarget

The resolution algorithm, implemented in lines 35-90 of plugins/codex/scripts/lib/git.mjs, follows a strict three-tier priority order to determine the review target.

1. Explicit --base Flag Detection

When users provide --base <ref>, Codex immediately forces branch mode. The current HEAD is diffed against the supplied base reference, bypassing all automatic detection logic and the default branch detection mechanism.

2. Explicit --scope Flag Selection

The --scope parameter allows direct mode selection without specifying a base reference:

• --scope working-tree → Forces working-tree mode
• --scope branch → Forces branch mode using the repository's default branch (detected via detectDefaultBranch)

3. Automatic Selection (auto)

When no explicit flags are provided, Codex evaluates repository cleanliness through internal state checks:

• Dirty repository (staged, unstaged, or untracked changes present) → Selects working-tree mode
• Clean repository → Falls back to branch mode against the default branch

Return Value Structure

The function returns a standardized object containing the following properties:

• mode: Either "working-tree" or "branch"
• label: Human-readable description of the diff target (e.g., "working tree diff")
• baseRef: Present only in branch mode, indicating the reference to diff against
• explicit: Boolean indicating whether the choice originated from a user flag (true) or automatic detection (false)

Practical CLI Examples

Example 1: Default Auto-Detection on Dirty Repository

# Working directory has unstaged changes

codex review

Result:

{
  "mode": "working-tree",
  "label": "working tree diff",
  "explicit": false
}

Example 2: Explicit Base Branch

codex review --base main

Result:

{
  "mode": "branch",
  "label": "branch diff against main",
  "baseRef": "main",
  "explicit": true
}

Example 3: Explicit Scope to Branch

codex review --scope branch

Result (assuming the default branch is main):

{
  "mode": "branch",
  "label": "branch diff against main",
  "baseRef": "main",
  "explicit": true
}

Example 4: Explicit Scope to Working-Tree

codex review --scope working-tree

Result:

{
  "mode": "working-tree",
  "label": "working tree diff",
  "explicit": true
}

Integration with the Review Pipeline

The resolved target propagates through the Codex architecture according to the following flow:

• plugins/codex/scripts/lib/codex.mjs consumes the target object when constructing native review requests
• plugins/codex/scripts/codex-companion.mjs orchestrates the call to resolveReviewTarget and validates the returned configuration before execution
• Unit tests in tests/git.test.mjs verify the resolution logic for flag precedence and auto-detection scenarios
• Integration tests in tests/runtime.test.mjs confirm that the CLI correctly applies the selected target during actual review requests

Summary

• resolveReviewTarget in plugins/codex/scripts/lib/git.mjs (lines 35-90) implements the core resolution logic for determining review targets
• Explicit flags take precedence: --base overrides --scope, which overrides automatic detection
• Auto mode selects working-tree for dirty repositories and branch mode for clean repositories against the default branch
• The function returns a standardized object with mode, label, baseRef, and explicit properties consumed by the broader Codex review pipeline

Frequently Asked Questions

What happens if I specify both --base and --scope flags?

The --base flag takes highest priority. When provided, Codex ignores --scope and any automatic detection, forcing branch mode against the specified reference. This precedence is encoded in the initial conditional checks of resolveReviewTarget in the source code.

How does Codex detect the default branch when using --scope branch?

The function calls detectDefaultBranch to identify the repository's default branch (typically main or master). This occurs automatically when --scope branch is specified without an explicit --base parameter, ensuring the review compares against the correct baseline even when the user doesn't specify one.

Can I force working-tree mode even if my repository is clean?

Yes. Pass --scope working-tree to bypass the automatic cleanliness check. This is useful when you want to review specific staged changes or when working with an empty working directory that should still be treated as a working-tree target for consistency in automation workflows.

Where is the review target resolution logic tested?

The core logic resides in tests/git.test.mjs, which contains unit tests for resolveReviewTarget covering flag precedence, auto-detection scenarios, and edge cases. Integration tests in tests/runtime.test.mjs verify that the CLI correctly applies these targets during actual review requests according to the openai/codex-plugin-cc source code.

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