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

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:

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

Review current branch against default:

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

Review against a custom base:

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

Programmatic Integration

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

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).

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