How the Codex Plugin Collects Review Context from the Git Working Tree

The Codex plugin extracts review context by running Git commands to determine the commit range between HEAD and the upstream branch, parsing the diff to identify changed files and line ranges, and sending this data as a structured 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 transforms raw Git working tree changes into structured review sessions. When you request a branch review, the plugin executes a sequence of Git operations to capture the exact state of your modifications, then transmits this context to the Codex backend through a typed RPC protocol.

The Review Start RPC Protocol

The review process begins with the review/start RPC method defined in plugins/codex/scripts/lib/app-server-protocol.d.ts. The request payload uses the ReviewStartParams type, which encapsulates the entire review context including file paths, change types, and modified line ranges.

The RPC mapping in the protocol file declares:

"review/start": { params: ReviewStartParams; result: ReviewStartResponse }

This method is invoked through the CodexAppServerClient, which handles the WebSocket communication with the Codex broker. The concrete TypeScript definitions for these parameters are generated in .generated/app-server-types/v2/index.js, ensuring type safety across the client-server boundary.

Step-by-Step Git Context Extraction

When the plugin receives a "review this branch" command, it executes a five-stage pipeline to harvest context from the Git working tree:

Detecting the Target Branch

The plugin first identifies the commit range to analyze by executing standard Git commands. It retrieves the current HEAD SHA using git rev-parse HEAD and determines the upstream comparison point with git rev-parse @{upstream}. These SHAs establish the base and head boundaries for the diff computation.

Computing the Diff

With the commit range established, the plugin runs git diff --name-status <base>..HEAD (or git diff --raw <base>..HEAD) to enumerate all changed files. This command returns the file paths alongside their status flags—indicating whether files were added, modified, or deleted—and provides the metadata necessary to calculate exact line ranges.

Building ReviewTarget Objects

For each changed file detected in the diff, the plugin constructs a ReviewTarget object containing:

• path: The relative file path from the repository root
• type: The change classification as added, modified, or deleted
• lineRanges: An array of [startLine, endLine] tuples representing the exact hunks that changed

These objects form the core data structure that represents the review scope, converting raw Git output into a machine-readable format that the Codex backend can process.

Sending the RPC Request

The plugin aggregates all ReviewTarget objects into the targets array within ReviewStartParams. It then invokes the RPC method through the CodexAppServerClient, transmitting the complete context to the Codex App Server. The server uses this precise change set to generate targeted review comments and suggestions.

Implementation Example

The following TypeScript illustrates how the plugin gathers Git context and initiates the review:

// Example: Starting a review from a branch
import { CodexAppServerClient } from "codex-app-server-client";

// 1️⃣ Create a client (the client knows how to talk to the Codex App Server)
const client = new CodexAppServerClient({
  brokerEndpoint: "wss://codex-broker.openai.com",
});

// 2️⃣ Gather review context (the utility function below internally runs the
//    Git commands described above)
async function getReviewContext(): Promise<ReviewStartParams> {
  // This is a simplified illustration – the real implementation lives inside
  // the plugin's source tree.
  const { execSync } = require("child_process");
  const base = execSync("git rev-parse @{upstream}").toString().trim();
  const head = execSync("git rev-parse HEAD").toString().trim();

  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",
        // For brevity we omit line‑range extraction here.
        lineRanges: [] as [number, number][],
      };
    });

  return { targets };
}

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

startReview().catch(console.error);

In this implementation, git rev-parse establishes the commit boundaries, while git diff --numstat provides the file change metrics. The resulting targets array conforms to the ReviewStartParams interface defined in app-server-protocol.d.ts, enabling the client.request("review/start", params) call to transmit the full context.

Summary

• The Codex plugin uses the review/start RPC method defined in plugins/codex/scripts/lib/app-server-protocol.d.ts to initiate review sessions.
• Git command execution (git rev-parse and git diff) extracts the current branch state and computes the exact diff between HEAD and the upstream branch.
• ReviewTarget objects encapsulate file paths, change types, and line ranges, providing a structured representation of the working tree changes.
• The CodexAppServerClient transmits the assembled ReviewStartParams to the Codex App Server, enabling context-aware code suggestions.

Frequently Asked Questions

What RPC method does the Codex plugin use to start a review?

The plugin uses the "review/start" RPC method defined in plugins/codex/scripts/lib/app-server-protocol.d.ts. This method accepts ReviewStartParams containing the review context and returns a ReviewStartResponse confirming the session initiation.

How does the plugin determine which files have changed?

The plugin executes git diff --name-status <base>..HEAD or git diff --raw <base>..HEAD to compare the current HEAD against the upstream branch. These commands return the status (added, modified, deleted) and paths of all changed files, which the plugin converts into ReviewTarget objects.

What information is included in a ReviewTarget object?

Each ReviewTarget includes three fields: path (the relative file path), type (the change classification as added, modified, or deleted), and lineRanges (an array of [startLine, endLine] tuples specifying the exact modified hunks in the file).

Where are the RPC protocol definitions located?

The protocol definitions are located in plugins/codex/scripts/lib/app-server-protocol.d.ts, which declares the method map including review/start. The concrete TypeScript types for ReviewStartParams and ReviewStartResponse are generated in .generated/app-server-types/v2/index.js and imported by the protocol file.

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