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

> Learn how Codex resolves review targets using working-tree or branch detection. Understand the logic behind its automatic detection and CLI flag evaluation.

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

---

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

```bash

# Working directory has unstaged changes

codex review

```

Result:

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

```

### Example 2: Explicit Base Branch

```bash
codex review --base main

```

Result:

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

```

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

```

Result:

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