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

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:

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:

{
  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

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

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.

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