# How the Codex Plugin Handles Git Repository Context for Code Reviews

> Learn how the Codex plugin uses a three-stage pipeline to detect Git repository context, select review modes, and collect diffs and metadata for effective code reviews.

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

---

**The Codex plugin resolves Git repository context through a three-stage pipeline—detecting the repository and baseline, selecting between working-tree or branch review modes, and collecting size-capped diffs and metadata—implemented in `plugins/codex/scripts/lib/git.mjs`.**

The `openai/codex-plugin-cc` repository contains a specialized library that powers intelligent code reviews by precisely capturing repository state. When you trigger a review command, the plugin must determine exactly what code changed and assemble that context into a model-friendly payload. This process relies on a dedicated Git utility module that validates the repository, resolves comparison targets, and safely extracts diffs while respecting token budgets.

## Three-Stage Git Context Resolution

The Git context infrastructure follows a logical progression from environment validation to data collection. According to the source code in `plugins/codex/scripts/lib/git.mjs`, the pipeline executes three distinct stages:

1. **Repository detection and baseline resolution** – Validates the working directory and determines the base reference
2. **Review target selection** – Chooses between working-tree or branch comparison based on repository state and user preferences
3. **Context assembly** – Gathers diffs, commit logs, and file metadata while enforcing size constraints

## Step 1: Repository Detection and Baseline Resolution

### Validating the Git Repository

Before any Git operations occur, the plugin must confirm it is running inside a valid Git repository. The `ensureGitRepository` function (lines 78–88) executes `git rev-parse --show-toplevel` to verify repository membership. If this command fails, the review aborts immediately with a clear error message, preventing undefined behavior in non-Git directories.

### Resolving the Base Reference

Once validated, the plugin determines what to compare against. The `detectDefaultBranch` function (lines 94–115) implements a fallback strategy:

- First, it attempts to read the remote-HEAD symbolic reference
- If unavailable, it defaults to common branch names: `main`, `master`, or `trunk`

Alternatively, users can bypass auto-detection by supplying a specific `--base` argument, which takes precedence over the automatic detection logic.

## Step 2: Selecting the Review Target Mode

### Understanding Scope Options

The `resolveReviewTarget` function (lines 35–91) controls how the plugin interprets the review request. It supports three scope values:

- **`working-tree`** – Always compares the current working directory against the base reference, including staged, unstaged, and untracked changes
- **`branch`** – Compares the current branch's HEAD against the base reference, ignoring working directory modifications
- **`auto`** (default) – Intelligently selects the appropriate mode based on repository state

### The Auto-Detection Logic

When `scope: "auto"` is specified (the default), the plugin examines the repository's dirty state. If the working tree contains modifications, staged files, or untracked content, it automatically selects **working-tree** mode. On a clean repository with no pending changes, it switches to **branch** mode, generating a diff between the current branch and the detected default branch (`main`/`master`).

## Step 3: Assembling the Review Context

Depending on the mode selected, `collectReviewContext` (lines 99–147) delegates to specialized collectors that gather different data profiles while applying strict size limits.

### Working Tree Context Collection

The `collectWorkingTreeContext` helper (lines 25–61) captures the immediate state of development:

- Retrieves staged and unstaged changes via `git diff`
- Lists untracked files using `git ls-files`
- Optionally inlines full diff content if file count stays within `maxInlineFiles` and total bytes remain under `maxInlineDiffBytes`

The implementation also caps individual untracked file sizes using `MAX_UNTRACKED_BYTES` to prevent binary blobs or large generated files from consuming the context window.

### Branch Context Collection

For historical comparisons, `collectBranchContext` (lines 62–89) executes:

1. Computes the merge base between current branch and base ref using `git merge-base`
2. Builds a commit range from merge base to HEAD
3. Extracts the commit log, diff statistics, and full branch diff
4. Applies the same size limits as working-tree mode

This produces a comprehensive view of changes introduced since the branch diverged from the default line.

### Size Limits and Safety Guards

The library enforces several protective constraints:

- **Diff limits**: `maxInlineFiles` (default-controlled) and `maxInlineDiffBytes` (e.g., 200KB) prevent context overflow
- **Untracked file caps**: `MAX_UNTRACKED_BYTES` filters out oversized new files
- **Shell execution**: All Git commands run with `shell: false` in the `runCommand`/`runCommandChecked` helpers (located in `plugins/codex/scripts/lib/process.mjs`), ensuring read-only operations and preventing shell injection vulnerabilities

## Implementation Architecture

The Git context system relies on a modular architecture within the `plugins/codex/scripts/lib/` directory:

- **`git.mjs`** – Core orchestration logic for detection, resolution, and collection
- **`process.mjs`** – Safe process execution utilities that disable shell interpretation
- **`fs.mjs`** – File type detection utilities (e.g., `isProbablyText`) used when processing untracked files

The test suite in `tests/git.test.mjs` provides coverage for `resolveReviewTarget` and `collectReviewContext`, ensuring reliable behavior across different repository states.

## Practical Usage Example

To manually trigger context collection in a script:

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

// Resolve the target (auto-detects working-tree vs branch)
const target = resolveReviewTarget(process.cwd(), { scope: "auto" });

// Collect the full review context with size constraints
const review = await collectReviewContext(process.cwd(), target, {
  maxInlineFiles: 5,          // limit number of files shown inline
  maxInlineDiffBytes: 200*1024 // 200 KB diff size limit
});

console.log(review.summary); // Human-readable one-liner
console.log(review.content); // Full markdown blob sent to the LLM

```

When executed on a repository with uncommitted changes, this returns working-tree diffs. On a clean repository, it automatically switches to a branch diff against the detected default branch.

## Summary

- The Codex plugin implements Git context handling in `plugins/codex/scripts/lib/git.mjs` through a validated three-stage pipeline
- **Repository validation** via `ensureGitRepository` ensures operations occur only within valid Git workspaces
- **Baseline detection** uses `detectDefaultBranch` with fallback logic for `main`/`master`/`trunk` when no `--base` is specified
- **Mode selection** through `resolveReviewTarget` supports explicit `working-tree` or `branch` scopes, plus intelligent `auto` detection based on dirty state
- **Context collection** via `collectReviewContext` and its specialized helpers gathers diffs, logs, and status while respecting `maxInlineFiles` and `maxInlineDiffBytes` limits
- **Security measures** include `shell: false` execution and read-only Git operations across all helper modules

## Frequently Asked Questions

### How does the Codex plugin detect the default branch?

The `detectDefaultBranch` function first attempts to resolve the remote-HEAD symbolic reference. If that fails, it iterates through common default names—`main`, `master`, and `trunk`—returning the first match found in the repository. This ensures the plugin works across different Git hosting platforms and repository configurations without explicit configuration.

### What is the difference between working-tree and branch review modes?

**Working-tree** mode captures the current state of your working directory, including staged, unstaged, and untracked files, comparing them against the base reference. **Branch** mode ignores working directory changes and instead compares the current branch's HEAD commit against the base reference, showing only committed changes. The `auto` scope automatically selects working-tree when modifications exist, otherwise defaulting to branch mode.

### How does the plugin prevent token limit issues?

The context collection system implements multiple safeguards: `maxInlineFiles` limits the number of files displayed inline, `maxInlineDiffBytes` caps the total diff size (commonly set to 200KB), and `MAX_UNTRACKED_BYTES` restricts individual untracked file inclusion. Additionally, the `isProbablyText` helper from `fs.mjs` filters out binary files that would waste tokens without providing meaningful review context.

### Is it safe to run the Codex plugin in any directory?

The plugin validates the working directory before executing Git commands. The `ensureGitRepository` function runs `git rev-parse --show-toplevel` and aborts with an error if the current directory is not inside a Git repository. Furthermore, all Git invocations use `shell: false` in the process execution helpers, preventing shell injection and ensuring commands execute in a read-only, restricted environment.