# Working-Tree vs Branch Review Targets in the OpenAI Codex Plugin

> Understand the difference between working tree and branch review targets in the OpenAI Codex plugin. Learn how each analyzes your code for effective reviews and improved workflows.

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

---

**The `working-tree` review target analyzes your current working directory including staged, unstaged, and untracked files, while the `branch` target computes a diff between your current branch and a base reference using `git merge-base`.**

The openai/codex-plugin-cc repository provides an intelligent code review system that adapts its analysis scope based on the selected review target. Understanding the distinction between **working-tree** and **branch** review targets ensures you analyze exactly the changes you intend, whether they are uncommitted local modifications or committed branch differences.

## Core Differences Between Review Targets

The Codex plugin implements two fundamentally different review modes in `plugins/codex/scripts/lib/git.mjs`. Each mode collects distinct context about your repository state.

### Working-Tree: Uncommitted Changes

The **working-tree** target captures the current state of your working directory. According to the source code in `plugins/codex/scripts/lib/git.mjs` (lines 52‑58 and 76‑82), this mode reviews:

- Staged changes (`git diff --cached`)
- Unstaged modifications (`git diff`)
- Untracked files

When you request a working-tree review, the plugin invokes `collectWorkingTreeContext` (lines 25‑60), which executes `git status` and aggregates diffs alongside any untracked files present in your repository.

### Branch: Commit-to-Commit Diffs

The **branch** target performs a comparative review between two commits. As implemented in lines 66‑73 and 84‑90 of `git.mjs`, this mode:

- Computes a merge-base between the current branch and a target reference
- Gathers commit logs and diff statistics
- Optionally produces the full branch diff

The function `collectBranchContext` (lines 62‑90) handles this by running `git merge-base` to find the common ancestor, then collecting the relevant commit history and differences.

## How the Plugin Selects a Review Target

The `resolveReviewTarget` function in `plugins/codex/scripts/lib/git.mjs` determines which mode to use based on CLI flags and repository state.

### Explicit Scope Selection

You can force a specific target using the `--scope` flag passed to `plugins/codex/scripts/codex-companion.mjs`:

- `--scope working-tree` immediately returns a target with `mode: "working-tree"` (lines 52‑58)
- `--scope branch` returns a target with `mode: "branch"` (lines 66‑73)

### Automatic Detection Logic

When `--scope auto` is specified (the default), the plugin applies conditional logic:

1. **Base reference override**: If you provide `--base <ref>`, the plugin forces a branch target regardless of working tree state (lines 43‑50)
2. **Dirty working tree**: If `state.isDirty` returns true (detected via `getWorkingTreeState` in `plugins/codex/scripts/lib/state.mjs`), the plugin selects **working-tree** mode (lines 76‑82)
3. **Clean working tree**: When no uncommitted changes exist, the plugin detects the default branch via `detectDefaultBranch` and creates a **branch** target (lines 84‑90)

## Context Collection Implementation

Each review target triggers a specific context gathering pipeline that feeds data to the Codex analysis engine. Both pipelines rely on `plugins/codex/scripts/lib/process.mjs` to execute Git commands safely.

### Working-Tree Context Pipeline

When `collectWorkingTreeContext` executes (lines 25‑60), it:

1. Retrieves the working tree state using `getWorkingTreeState`
2. Captures staged diffs via `git diff --cached`
3. Captures unstaged diffs via `git diff`
4. Lists untracked files for inclusion in the review

This ensures the review covers every modification present in your working directory, regardless of staging status.

### Branch Context Pipeline

When `collectBranchContext` runs (lines 62‑90), it:

1. Calculates the merge-base between the current HEAD and the target base reference
2. Collects the commit log between the merge-base and HEAD
3. Gathers diff statistics using `git diff --stat`
4. Optionally includes the full diff content when `includeDiff` is enabled

This approach provides a high-level overview of branch changes while supporting deep inspection of specific commits.

## Command-Line Usage Examples

You can invoke these review targets directly from the CLI using `codex-companion.mjs`.

**Review uncommitted changes:**

```bash
node scripts/codex-companion.mjs review --scope working-tree

```

**Review current branch against default:**

```bash
node scripts/codex-companion.mjs review --scope branch

```

**Review against a custom base:**

```bash
node scripts/codex-companion.mjs review --base release-1.2.0

```

## Programmatic Integration

You can also resolve review targets programmatically in Node.js applications:

```javascript
import { resolveReviewTarget, collectReviewContext } from "./plugins/codex/scripts/lib/git.mjs";

const cwd = process.cwd();
const target = resolveReviewTarget(cwd, { scope: "working-tree" }); // or "branch"
const context = await collectReviewContext(cwd, target, { includeDiff: true });

console.log(context.summary);   // Concise description of the selected mode
console.log(context.content);   // Full diff or status information

```

This API allows custom tools built on the openai/codex-plugin-cc codebase to leverage the same Git detection logic used by the CLI.

## Summary

- The **working-tree** review target analyzes staged, unstaged, and untracked files in your current working directory via `collectWorkingTreeContext`.
- The **branch** review target computes diffs between commits using `git merge-base` and `collectBranchContext`.
- The `resolveReviewTarget` function in `git.mjs` automatically selects the appropriate mode based on the `--scope` flag, `--base` parameter, and working tree cleanliness.
- Explicit `--scope` flags override automatic detection, while `--base` always forces branch mode.

## Frequently Asked Questions

### When should I use working-tree versus branch review targets?

Use **working-tree** when you want feedback on code you are currently writing but have not yet committed, including experimental changes or partial implementations. Use **branch** when you need a review of complete, committed changes before merging, such as pull request preparation or release validation.

### How does the plugin handle untracked files?

The working-tree review explicitly includes untracked files in the analysis context. According to lines 25‑60 of `git.mjs`, `collectWorkingTreeContext` lists untracked files alongside staged and unstaged changes, ensuring new files receive the same review coverage as modified existing files.

### Can I review against a specific base commit instead of the default branch?

Yes. Supply the `--base` flag with any valid Git reference (commit SHA, tag, or branch name). As implemented in lines 43‑50 of `git.mjs`, providing a `--base` parameter forces branch mode and uses your specified reference instead of the auto-detected default branch.

### What happens if I don't specify a scope flag?

When `--scope` is omitted or set to `auto`, the plugin checks your working tree state via `getWorkingTreeState`. If uncommitted changes exist, it defaults to **working-tree** mode (lines 76‑82); if the working tree is clean, it defaults to **branch** mode against the detected default branch (lines 84‑90).