# Codex Plugin Review Context Collection Process: How Git Diffs Are Gathered

> Discover how the Codex plugin collects review context by gathering Git diffs. Learn about its Git commands and payload formatting for inline or separate diff fetching.

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

---

**The Codex plugin assembles a review context by running targeted Git commands in `plugins/codex/scripts/lib/git.mjs` to detect changes, measure diff size, and format markdown payloads that either embed diffs inline or instruct Codex to fetch them separately.**

The `openai/codex-plugin-cc` repository implements an intelligent **review context collection process** that prepares code changes for AI analysis. At the heart of this system is the `collectReviewContext` function, which orchestrates Git operations to capture working tree modifications or branch differences. This process automatically determines whether to embed full diffs directly in the prompt or delegate retrieval to Codex based on configurable byte limits and file counts.

## Resolving the Review Target

The collection process begins with `resolveReviewTarget` in **`plugins/codex/scripts/lib/git.mjs`**, which determines whether to examine the working tree or compare branches.

The function inspects the requested scope (`auto`, `working-tree`, or `branch`) along with any explicit `--base` argument. If the repository contains staged, unstaged, or untracked files and no explicit scope is provided, it defaults to a working tree review. Otherwise, it falls back to a branch comparison against the default branch detected via `detectDefaultBranch`.

The returned object specifies the mode (`"working-tree"` or `"branch"`), a human-readable label, and the reference for branch diffs when applicable.

## Measuring Diff Size and Selecting Input Mode

Before collecting content, the plugin measures the total diff size to decide between **inline-diff** and **self-collect** modes. This prevents oversized payloads from being embedded directly in prompts.

The `measureGitOutputBytes` function executes Git commands with a limited buffer (`maxBuffer`) to capture output size without loading the full content into memory. For working tree reviews, `measureCombinedGitOutputBytes` aggregates the size of both staged and unstaged diffs.

These measurements are compared against two thresholds:
- **`maxInlineFiles`**: Default limit of 2 files
- **`maxInlineDiffBytes`**: Default limit of 256 KB

If the diff exceeds these limits, `inputMode` is set to `"self-collect"`, instructing Codex to retrieve the diff independently. Otherwise, the plugin uses `"inline-diff"` to embed the content directly.

## Collecting Working Tree Context

For working tree reviews, `collectWorkingTreeContext` gathers the current repository state through three specific Git commands executed via `getWorkingTreeState`:

```js
git diff --cached --name-only    // staged files
git diff --name-only             // unstaged files  
git ls-files --others --exclude-standard  // untracked files

```

The context builder then formats a markdown payload containing:
- `git status --short --untracked-files=all` for the status summary
- `git diff --cached --binary` for staged changes
- `git diff --binary` for unstaged changes

Untracked files are processed through `formatUntrackedFile`, which reads file content only if the file is text-based and under 24 KB. Binary files are excluded from the inline content.

## Collecting Branch Context

When reviewing branch differences, `collectBranchContext` constructs a merge base and commit range (`<baseRef>...HEAD`) to identify relevant changes.

The branch collector executes:
- `git log --oneline --decorate <range>` for commit history
- `git diff --stat <range>` for change statistics
- `git diff --binary <range>` for the full diff (when inline mode is active)

This approach provides Codex with both high-level metadata and detailed line-by-line changes when the size permits inline transmission.

## Assembling the Final Review Context

The `collectReviewContext` function assembles the final structure returned to the caller:

```js
{
  cwd, repoRoot, branch, target,
  fileCount: details.changedFiles.length,
  diffBytes,
  inputMode: includeDiff ? "inline-diff" : "self-collect",
  collectionGuidance: buildAdversarialCollectionGuidance({ includeDiff }),
  ...details
}

```

The `collectionGuidance` field provides instructions to Codex regarding how to handle the diff based on the selected input mode. When `includeDiff` is false, Codex receives guidance to fetch the diff itself rather than expecting it in the context.

## Code Examples

### Working Tree Review with Auto-Detection

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

const cwd = process.cwd();
const target = resolveReviewTarget(cwd, {
  scope: "auto"
});
const context = collectReviewContext(cwd, target);

console.log(context.inputMode);  // "inline-diff" for small changes
console.log(context.content);    // Markdown with diffs and status

```

### Branch Review with Custom Size Limits

```javascript
const target = resolveReviewTarget(cwd, {
  base: "origin/main"
});
const context = collectReviewContext(cwd, target, {
  maxInlineFiles: 5,
  maxInlineDiffBytes: 500000
});

console.log(context.inputMode);  // "self-collect" if diff exceeds limits

```

## Summary

- **`collectReviewContext`** in `plugins/codex/scripts/lib/git.mjs` orchestrates the entire collection process, from target resolution to final assembly.
- **`resolveReviewTarget`** automatically selects between working tree and branch reviews based on repository state and explicit arguments.
- Size measurement functions compare diff bytes against `maxInlineDiffBytes` (256 KB default) and `maxInlineFiles` (2 files default) to determine the input mode.
- Working tree collection captures staged, unstaged, and untracked files while filtering binary content and files over 24 KB.
- Branch collection uses merge-base detection to generate commit ranges and statistics via `git log` and `git diff --stat`.

## Frequently Asked Questions

### What is the difference between inline-diff and self-collect modes?

**Inline-diff** embeds the full Git diff directly into the review context markdown sent to Codex, suitable for small changes under the byte and file count limits. **Self-collect** omits the diff content from the context and instead provides instructions for Codex to retrieve the diff independently, which the system uses when changes exceed `maxInlineDiffBytes` or `maxInlineFiles` to avoid prompt size limitations.

### How does the plugin handle untracked files?

The plugin lists untracked files using `git ls-files --others --exclude-standard` and processes them through `formatUntrackedFile`. Only text files under 24 KB are included in the inline context; binary files and large files are acknowledged by filename but their contents are excluded from the markdown payload to prevent noise and size bloat.

### What Git commands measure diff size before collection?

The plugin uses `measureGitOutputBytes` to run Git commands with a restricted buffer size, specifically targeting `git diff --cached` and `git diff` for working tree measurements. For branch reviews, it measures the output of `git diff <range>` to determine whether the content fits within the `maxInlineDiffBytes` threshold before attempting to load the full diff into memory.

### How does the plugin decide between working tree and branch review?

The `resolveReviewTarget` function defaults to working tree review when the repository is dirty (contains staged, unstaged, or untracked changes) and no explicit scope or base reference is provided via command-line arguments. If the working tree is clean or a specific base branch is requested, the plugin switches to branch comparison mode against the detected default branch or specified reference.