How Review Targets Are Resolved (Working Tree vs Branch) in the OpenAI Codex Plugin

Codex resolves review targets by checking for explicit --base or --scope flags first, then automatically selecting working-tree mode if uncommitted changes exist or branch mode if the repository is clean.

The OpenAI Codex plugin determines whether to review your working tree or compare against a base branch using the resolveReviewTarget function in plugins/codex/scripts/lib/git.mjs. This utility evaluates CLI flags and repository state to decide whether to diff against uncommitted changes or a reference branch. Understanding how review targets are resolved helps you control exactly what code gets analyzed during the review process.

The resolveReviewTarget Implementation

In plugins/codex/scripts/lib/git.mjs (lines 35-90), the resolveReviewTarget function implements a hierarchical decision tree. It examines command-line arguments and repository status to return a structured target object that drives the entire review process.

Priority Order for Target Resolution

The function follows strict precedence logic when determining the review target, checking conditions in the following order:

Explicit --base Flag (Highest Priority)

When you provide --base <ref>, the system forces branch mode. It diffs the current HEAD against the supplied reference, overriding all other logic including automatic detection and --scope flags.

Explicit --scope Flag

The --scope parameter accepts two explicit values:

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

Automatic Selection (Auto Mode)

When no flags are provided, the function checks repository cleanliness:

• Dirty repository: Any staged, unstaged, or untracked changes trigger working-tree mode
• Clean repository: Falls back to branch mode against the default branch

Return Value Structure

The function returns an object containing:

• mode: Either "working-tree" or "branch"
• label: Human-readable description of the diff target
• baseRef: The base reference (only present in branch mode)
• explicit: Boolean indicating whether the choice came from user flags

Usage Examples

Example 1: Auto Mode on Dirty Repository

# Working directory has unstaged changes

codex review

Returns:

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

The function detects state.isDirty and returns the working-tree target.

Example 2: Explicit Base Reference

codex review --base main

Returns:

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

The --base option overrides any auto logic.

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

Returns:

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

Integration with the Review Pipeline

The resolved target feeds into the broader review system. According to the source code, plugins/codex/scripts/lib/codex.mjs consumes the target object when constructing native review requests, while plugins/codex/scripts/codex-companion.mjs calls resolveReviewTarget and validates the selection before execution. Unit tests in tests/git.test.mjs verify the resolution logic, and integration tests in tests/runtime.test.mjs confirm the CLI respects these targets.

Summary

• The resolveReviewTarget function in plugins/codex/scripts/lib/git.mjs (lines 35-90) determines whether Codex reviews the working tree or a branch.
• Resolution follows strict priority: --base flag > --scope flag > automatic detection.
• Automatic mode selects working-tree if the repository has uncommitted changes, otherwise compares against the default branch.
• The function returns a structured object with mode, label, baseRef, and explicit properties used by codex-companion.mjs and codex.mjs.

Frequently Asked Questions

What is the default behavior if I run codex review without flags?

If your repository contains any uncommitted changes (staged, unstaged, or untracked), Codex defaults to working-tree mode and reviews your current changes. If the repository is clean, it compares the current HEAD against the default branch detected by the detectDefaultBranch function.

Does the --base flag override the --scope flag?

Yes. The --base flag takes highest priority in the resolveReviewTarget logic. When provided, it forces branch mode against the specified reference regardless of other flags or repository state, as implemented in the priority check at the start of the function.

How does Codex detect the default branch for --scope branch?

The plugin uses the detectDefaultBranch utility function to identify the repository's default branch (typically main or master) when you explicitly request --scope branch or when auto-fallback to branch mode occurs on a clean repository.

Where are the tests for review target resolution?

Unit tests for the resolution logic are located in tests/git.test.mjs, which verifies the behavior of resolveReviewTarget for different scenarios. Integration tests confirming that the CLI respects the chosen target are in tests/runtime.test.mjs.

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