# Force working-tree review

> Understand how the Codex plugin resolves review targets, differentiating between working tree and branch detection for efficient code reviews.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-08-02

---

How the Codex Plugin Resolves Review Targets: Working Tree vs Branch Detection

**The Codex plugin resolves review targets through a priority-based algorithm in `resolveReviewTarget` that first checks for explicit `--base` or `--scope` flags, then automatically selects working-tree mode when uncommitted changes exist or branch mode against the default branch when the repository is clean.**

The `openai/codex-plugin-cc` repository implements intelligent target resolution to determine whether a code review should analyze your working directory changes or compare branches. Understanding how the plugin chooses between **working-tree** and **branch** modes helps you control exactly what gets reviewed when running `codex review` commands. The resolution logic lives in `plugins/codex/scripts/lib/git.mjs` and follows a strict priority order to balance explicit user intent with automatic detection.

## The Core Resolution Function

The `resolveReviewTarget` function in `plugins/codex/scripts/lib/git.mjs` (lines 35-90) serves as the single source of truth for determining review scope. This function analyzes repository state and user-provided flags to return a structured target object that downstream components consume when building review requests.

The function examines three potential inputs in strict priority order:

1. **Explicit `--base` flag** – Forces branch comparison against a specific reference
2. **Explicit `--scope` flag** – Directly selects either working-tree or branch mode  
3. **Automatic detection** – Inspects repository cleanliness to choose intelligently

## Priority 1: The `--base` Flag Override

When you supply `--base <ref>`, the plugin immediately enters **branch** mode. This flag takes precedence over all other options, diffing the current `HEAD` against your specified base reference.

```bash
codex review --base main

```

This returns a target object with `mode: "branch"`, `baseRef: "main"`, and `explicit: true`, bypassing all automatic detection logic.

## Priority 2: The `--scope` Flag Selection

The `--scope` flag provides explicit mode selection without specifying a particular branch reference:

- `--scope working-tree` → Targets uncommitted changes in your working directory
- `--scope branch` → Compares against the repository's default branch (detected via `detectDefaultBranch`)

```bash

# Force working-tree review

codex review --scope working-tree

# Force branch review against default branch

codex review --scope branch

```

When using `--scope branch` without `--base`, the system calls `detectDefaultBranch` (also in `git.mjs`) to identify whether to diff against `main`, `master`, or another default reference.

## Priority 3: Automatic Selection Logic

When no explicit flags are provided, the plugin enters **auto** mode and inspects repository state via the `state.isDirty` property. This boolean aggregates status across staged, unstaged, and untracked files.

If the repository contains **any uncommitted changes**, the function selects **working-tree** mode to review your active edits. If the repository is **completely clean**, it falls back to **branch** mode, comparing the current HEAD against the default branch.

This automatic behavior ensures that `codex review` without arguments does the right thing: reviewing your current work when you have edits, or reviewing branch divergence when you don't.

## Return Value Structure

Regardless of how the mode is determined, `resolveReviewTarget` returns a standardized object consumed by `plugins/codex/scripts/lib/codex.mjs` and validated in `plugins/codex/scripts/codex-companion.mjs`:

```javascript
{
  mode: "working-tree" | "branch",
  label: "working tree diff" | "branch diff against main",
  baseRef: "main" | undefined,  // Only present for branch mode
  explicit: true | false        // True if from --base or --scope
}

```

The `explicit` field allows the CLI to distinguish between user-intended overrides and automatic selections, which affects how results are displayed and cached.

## Practical Usage Examples

### Example 1: Default Behavior on Dirty Repository

When your working directory has unstaged modifications:

```bash
codex review

```

Resulting target object:

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

```

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

### Example 2: Explicit Base Reference

```bash
codex review --base feature/123

```

Result:

```json
{
  "mode": "branch",
  "label": "branch diff against feature/123",
  "baseRef": "feature/123",
  "explicit": true
}

```

### Example 3: Explicit Scope to Branch with Default Detection

```bash
codex review --scope branch

```

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
}

```

## Summary

- The `resolveReviewTarget` function in `plugins/codex/scripts/lib/git.mjs` (lines 35-90) implements a three-tier priority system for target resolution.
- **Explicit `--base`** always wins, forcing branch mode against the specified reference.
- **Explicit `--scope`** selects working-tree or branch mode, with branch mode using `detectDefaultBranch` to find the comparison target.
- **Automatic mode** inspects `state.isDirty`: uncommitted changes trigger working-tree review, while clean repositories trigger branch comparison against the default.
- The function returns a structured object with `mode`, `label`, `baseRef`, and `explicit` properties used by `codex.mjs` to construct native review requests.

## Frequently Asked Questions

### What happens if I specify both `--base` and `--scope`?

The `--base` flag takes precedence over `--scope` according to the priority logic in `git.mjs`. If you provide both, the plugin ignores the `--scope` value and uses the explicit base reference for branch comparison.

### How does the plugin detect whether to use main or master as the default branch?

The `detectDefaultBranch` function (located in `plugins/codex/scripts/lib/git.mjs`) interrogates the repository's symbolic refs and remote configuration to determine whether to diff against `main`, `master`, or another default branch when running in `--scope branch` mode or automatic branch fallback.

### Can I review untracked files in working-tree mode?

Yes. The automatic `state.isDirty` detection includes untracked files alongside staged and unstaged changes. When the plugin detects any uncommitted content—including new untracked files—it selects working-tree mode to ensure those files appear in the review context.

### Where are the tests for target resolution located?

Unit tests verifying `resolveReviewTarget` behavior live in `tests/git.test.mjs`, covering scenarios for dirty repositories, clean repositories, and explicit flag handling. Integration tests confirming CLI respect for chosen targets appear in `tests/runtime.test.mjs`.