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

> Discover how the OpenAI Codex plugin resolves review targets between working tree and branch modes. Learn about explicit flags and automatic selection for clean repositories and uncommitted changes.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals-guide
- Published: 2026-07-17

---

**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

```bash

# Working directory has unstaged changes

codex review

```

Returns:

```json
{
  "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

```bash
codex review --base main

```

Returns:

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

```

The `--base` option overrides any auto logic.

### Example 3: Explicit Scope to Branch

```bash
codex review --scope branch

```

Result (assuming the default branch is `main`):

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

```

### Example 4: Explicit Scope to Working-Tree

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

```

Returns:

```json
{
  "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`.