# How to Run Reviews Against Branch Comparisons in Codex

> Master branch comparisons in Codex. Run reviews against branch comparisons using the /codex:review command to simplify code reviews and track changes effectively.

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

---

**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:

```bash
/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:

```bash
/codex:review --base main --background

```

Monitor progress and retrieve results:

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

```

### Explicit Scope with Custom Base References

Combine scope flags with explicit base references for precision:

```bash
/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:

```bash
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.