How to Run Reviews Against Branch Comparisons in Codex

Use the /codex:review --base <ref> command to compare your current HEAD against any branch or commit, letting the plugin automatically compute the merge-base and diff range through the internal resolveReviewTarget function.

The openai/codex-plugin-cc repository provides a Codex CLI integration that enables AI-powered code reviews directly in your development workflow. When you need to run reviews against branch comparisons in Codex, the plugin's /codex:review command with the --base flag handles the Git operations automatically, calculating merge-bases and diff ranges without manual intervention.

How Branch Comparison Mode Works

When you invoke the review command with a base reference, the plugin switches to branch-mode to evaluate changes between commits.

Resolving the Review Target

In plugins/codex/scripts/lib/git.mjs, the resolveReviewTarget function (lines 34-46) immediately selects branch-mode when it detects the --base flag. It records your supplied reference as baseRef and sets the comparison point for the review.

Building the Diff Range

The helper buildBranchComparison (lines 68-74) in the same file computes three critical elements:

• The merge-base between your current HEAD and the target branch
• The commit range (<mergeBase>..HEAD) for generating the diff
• The review range (<baseRef>…HEAD) sent to the Codex model

If you omit --base, the plugin attempts auto-detection via detectDefaultBranch (lines 93-115), searching for main, master, or trunk. However, explicit base references provide deterministic comparisons essential for CI/CD pipelines and release branch reviews.

Running Reviews Against Branch Comparisons

Use these practical patterns to review feature branches, release candidates, or arbitrary commits.

Compare Current Branch Against Main

From any feature branch, execute:

/codex:review --base main

This triggers resolveReviewTarget with base: "main", activating branch-mode. The buildBranchComparison function finds the merge-base between HEAD (your feature branch tip) and main, then transmits the diff main...HEAD to the Codex CLI.

Background Reviews for Large Diffs

For extensive changes that might timeout, run asynchronously:

/codex:review --base main --background

Monitor progress and retrieve results:

/codex:status
/codex:result <job-id>

Explicit Scope with Custom Base References

Combine scope flags with explicit base references for precision:

/codex:review --scope branch --base release/v1.2

Even when --scope is set to branch, providing --base overrides automatic detection and forces comparison against release/v1.2.

Programmatic Usage via Node.js

Invoke the companion script directly for automation pipelines:

node plugins/codex/scripts/codex-companion.mjs review --base main

The command-line argument parser (lines 80-81 in codex-companion.mjs) accepts the same flags as the chat interface, making it suitable for GitHub Actions or local scripts.

Summary

• The /codex:review --base <ref> command activates branch-mode in plugins/codex/scripts/lib/git.mjs
• resolveReviewTarget (lines 34-46) records your base reference and selects the comparison mode
• buildBranchComparison (lines 68-74) automatically calculates merge-bases and diff ranges
• Always provide explicit --base values for deterministic reviews against release branches or main
• Use --background for large diffs and retrieve results via /codex:result
• Direct script invocation via codex-companion.mjs supports automation workflows

Frequently Asked Questions

What happens if I don't specify a --base flag?

The plugin calls detectDefaultBranch (lines 93-115) to auto-detect your default branch (checking for main, master, or trunk in that order). While convenient for local development, explicit --base references are recommended for reproducible results in CI/CD environments.

How does Codex determine which commits to review?

The buildBranchComparison function computes the merge-base between your current HEAD and the specified base reference, then creates a diff range from that merge-base to HEAD. This ensures you only review changes introduced since the branches diverged, not the entire branch history.

Can I review against specific commits instead of branches?

Yes. The --base flag accepts any valid Git reference, including commit SHAs, tags, or branch names. The resolveReviewTarget function treats all references identically, creating the appropriate comparison range regardless of whether you specify a branch name or commit hash.

Where are the branch comparison tests located?

The test suite confirms branch comparison functionality in tests/runtime.test.mjs (line 359) and verifies documentation accuracy in tests/commands.test.mjs (line 165), ensuring the --base <ref> usage works as documented in the README.

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