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

> Discover how the Codex plugin gathers review context by analyzing Git commands, parsing diffs, and sending structured data to the Codex App Server for efficient code review.

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

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/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:

```typescript
"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`](https://github.com/openai/codex-plugin-cc/blob/main/.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:

```typescript
// 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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.generated/app-server-types/v2/index.js) and imported by the protocol file.