# How the Codex Plugin Collects Review Context from a Git Branch

> Discover how the Codex plugin collects review context from a git branch. It detects commits, computes diffs, and sends structured data to the Codex App Server. Learn more now.

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

---

**The Codex plugin collects review context from a git branch by executing Git commands to detect the current commit and upstream base, computing a diff of changed files and line ranges, and transmitting this structured data as a `ReviewStartParams` payload to the Codex App Server via the `"review/start"` RPC method.**

The `openai/codex-plugin-cc` repository implements a code review workflow that begins with precise Git diff extraction. When a user requests a branch review, the plugin translates the local Git state into a machine-readable format that the Codex backend uses to generate context-aware suggestions.

## The Review Initiation Flow

The plugin follows a five-step pipeline to transform raw Git data into a structured review request. Each step maps directly to specific implementation details in the source code.

### 1. Detect the Target Branch

The plugin first identifies the commit range to analyze. It executes standard Git commands to capture the current state:

- `git rev-parse HEAD` retrieves the current commit SHA
- `git rev-parse @{upstream}` identifies the base branch SHA

These commands establish the exact boundaries of the review context.

### 2. Compute the Diff

Using the detected SHAs, the plugin generates a detailed file list. It runs `git diff --name-status <base>..HEAD` or `git diff --raw <base>..HEAD` to enumerate all changed files. This output includes the file status—whether files were **added**, **modified**, or **deleted**—and serves as the foundation for the review targets.

### 3. Build ReviewTarget Objects

For each changed file, the plugin constructs a `ReviewTarget` object. According to the App-Server protocol definitions in [`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts), this object contains:

- `path`: The relative file path from repository root
- `type`: The change classification (`added`, `modified`, or `deleted`)
- `lineRanges`: An array of `[startLine, endLine]` tuples covering the specific hunks that changed

### 4. Assemble ReviewStartParams

The plugin aggregates all `ReviewTarget` objects into a `ReviewStartParams` structure. This type is imported from the generated App-Server types located at [`.generated/app-server-types/v2/index.js`](https://github.com/openai/codex-plugin-cc/blob/main/.generated/app-server-types/v2/index.js). The structure may also include optional metadata, such as a user-provided review prompt.

### 5. Send the RPC

Finally, the plugin transmits the data via the `CodexAppServerClient`. The RPC method map in [`app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/app-server-protocol.d.ts) defines the interface as `"review/start": { params: ReviewStartParams; result: ReviewStartResponse }`. The server receives the complete diff context and uses it to generate targeted review comments.

## Technical Implementation Details

### Detecting Branch Commits with Git Commands

The plugin relies on shell execution of Git commands to determine the review boundaries. By comparing `HEAD` against `@{upstream}`, it automatically detects the commit range representing the current branch's changes relative to its base.

### Computing File Diffs and Change Status

The `git diff --name-status` command provides a concise output that the plugin parses to determine file states. For line-range extraction, the plugin analyzes the diff hunks to populate the `lineRanges` array in each `ReviewTarget`, ensuring the Codex backend knows exactly which lines require review.

### Building the ReviewTarget Objects

The `ReviewTarget` type is part of the App-Server RPC protocol. Each instance represents a single file in the change set. The `lineRanges` field is particularly critical—it allows the backend to focus its analysis on specific code blocks rather than entire files.

### RPC Transmission via review/start

The `CodexAppServerClient` class implements the `request` method used to invoke the `"review/start"` endpoint. This method serializes the `ReviewStartParams` and sends it to the broker endpoint (typically `wss://codex-broker.openai.com`), establishing the review session.

## Code Example: Gathering Review Context

The following TypeScript illustrates how the plugin combines Git commands with the RPC client to initiate a review:

```typescript
import { CodexAppServerClient } from "codex-app-server-client";

// Create a client instance
const client = new CodexAppServerClient({
  brokerEndpoint: "wss://codex-broker.openai.com",
});

// Gather review context from Git
async function getReviewContext(): Promise<ReviewStartParams> {
  const { execSync } = require("child_process");
  
  // Detect commit range
  const base = execSync("git rev-parse @{upstream}").toString().trim();
  const head = execSync("git rev-parse HEAD").toString().trim();
  
  // Get changed files
  const diff = execSync(`git diff --numstat ${base}..${head}`).toString();
  const targets = diff.split("\n")
    .filter(Boolean)
    .map(line => {
      const [added, deleted, file] = line.split("\t");
      return {
        path: file,
        type: (added === "0" && deleted === "0") ? "deleted" :
              (added === "0") ? "modified" : "added",
        lineRanges: [] as [number, number][], // Simplified for brevity
      };
    });

  return { targets };
}

// Initiate the review
async function startReview() {
  const params = await getReviewContext();
  const response = await client.request("review/start", params);
  console.log("Review started:", response);
}

startReview().catch(console.error);

```

This example demonstrates the core pattern: execute Git commands to build the `targets` array, then pass it to the `client.request` method using the exact shape defined in [`app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/app-server-protocol.d.ts).

## Key Source Files

The implementation spans several critical files in the `openai/codex-plugin-cc` repository:

- **[`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts)**: Declares the RPC method map, including the `"review/start"` entry and its `ReviewStartParams` parameter type.
- **[`.generated/app-server-types/v2/index.js`](https://github.com/openai/codex-plugin-cc/blob/main/.generated/app-server-types/v2/index.js)**: Contains the concrete TypeScript definitions for `ReviewStartParams` and `ReviewStartResponse`.
- **[`plugins/codex/scripts/lib/codex-app-server-client.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/codex-app-server-client.ts)**: Implements the `CodexAppServerClient` class and its `request` method for RPC transmission.
- **[`README.md`](https://github.com/openai/codex-plugin-cc/blob/main/README.md)**: Provides architectural overview of the plugin's Git integration.

## Summary

- The Codex plugin initiates branch reviews by sending a `review/start` RPC to the App Server.
- It uses `git rev-parse` and `git diff` commands to detect the current branch and compute file changes.
- Each changed file becomes a `ReviewTarget` object containing path, type, and specific line ranges.
- The `ReviewStartParams` structure aggregates these targets and travels to the backend via `CodexAppServerClient`.
- Source definitions in [`app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/app-server-protocol.d.ts) govern the exact data structures used in the exchange.

## Frequently Asked Questions

### What Git commands does the Codex plugin use to detect branch changes?

The plugin executes `git rev-parse HEAD` to get the current commit and `git rev-parse @{upstream}` to identify the base branch. For file enumeration, it uses `git diff --name-status <base>..HEAD` or `git diff --raw <base>..HEAD` to determine which files changed and their status.

### What data structure does the plugin send to the Codex App Server?

The plugin transmits a `ReviewStartParams` object, which contains an array of `ReviewTarget` objects. Each target includes the file `path`, change `type` (added/modified/deleted), and `lineRanges` specifying exactly which lines changed.

### How does the plugin handle deleted files in the review context?

Deleted files are included in the `targets` array with `type: "deleted"`. The `lineRanges` field for deleted files would typically be empty or indicate the removed line positions, allowing the backend to understand that the file no longer exists in the current branch.

### Where is the review/start RPC method defined in the source code?

The method is defined in [`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts) within the RPC method map. The line specifies `"review/start": { params: ReviewStartParams; result: ReviewStartResponse }`, linking the operation to its input and output types.