How the Codex Plugin Collects Review Context from a Git Branch

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, 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. 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 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:

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.

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: Declares the RPC method map, including the "review/start" entry and its ReviewStartParams parameter type.
• .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: Implements the CodexAppServerClient class and its request method for RPC transmission.
• 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 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 within the RPC method map. The line specifies "review/start": { params: ReviewStartParams; result: ReviewStartResponse }, linking the operation to its input and output types.

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