Claude Review Bridge — Codex + Gemini

MCP server for automated code review. Claude Code writes the code; a second model reviews it and structured feedback comes back inline, no copy-pasting between tools. The reviewer is OpenAI Codex by default, or Google Gemini (via the Antigravity agy CLI).

Works with a subscription you already have — $0 marginal cost. Codex runs on your ChatGPT plan; Gemini runs on your Google AI Pro plan.

Out of usage on one provider? When both are set up, the bridge automatically fails over to the other so a review still comes back — see Provider failover.

Quick Start

Add the MCP server to Claude Code (same for every provider):

claude mcp add codex-bridge -- npx -y codex-claude-bridge@latest

Then set up at least one reviewer. Codex is the default; set up both and the bridge fails over between them automatically.

Codex (default) — your ChatGPT subscription

Install the Codex CLI and sign in:

npm install -g @openai/codex
codex login

The SDK reads OAuth tokens from ~/.codex/auth.json (created by codex login); when no OPENAI_API_KEY is set it uses your ChatGPT subscription automatically. To pay per token instead, export OPENAI_API_KEY=sk-....

Gemini — your Google AI Pro subscription

Install the Antigravity (agy) CLI, then run it once to sign in with your Google account (AI Pro):

agy        # first run prompts a Google sign-in

Select Gemini with a .reviewbridge.json at your project root:

{ "provider": "gemini" }

Restart Claude Code after setup. The review tools are now available.

Prerequisites

• Node.js 18+ — nodejs.org

• Claude Code — code.claude.com

• Codex CLI (Codex path) — npm install -g @openai/codex, then codex login

• Antigravity agy CLI (Gemini path) — install it, then run agy to sign in (Google AI Pro)

Related MCP server: mcp-agent-review

What You Get

Once set up, Claude Code gains five new tools:

• review_plan — Send an implementation plan for architectural review. Get a verdict (approve / revise / reject) with specific findings.

• review_code — Send a code diff for review. Get findings with file and line references.

• review_precommit — Quick sanity check before committing. Automatically captures your staged git changes.

• review_status — Check whether a review is still in progress, completed, or failed.

• review_history — Look up past reviews by session or count.

All successful review calls return structured JSON with models[] (the providers/models that contributed) and provenance (whether the result was durably recorded, memory-only, or synthetic).

Responding-model evidence

Each models[] entry reports:

{
  "provider": "codex",
  "role": "review",
  "requested": null,
  "resolved": "gpt-6-astra",
  "observed": "gpt-6-astra",
  "evidence": "runtime_session_record"
}

• requested is the per-call/config selector considered for the turn. It is null for provider defaults and Codex resumes where no model override is applied.

• resolved is the concrete label selected or retained by the bridge.

• observed is a runtime-recorded label when one is available. Codex reads it from its local session record; Gemini reports the model agy named in its own init event for a run made by this server process, and null for a session this process did not run. A mismatch between resolved and observed is logged on stderr.

• role distinguishes normal review turns from deliberate-deep adjudication turns.

• evidence says whether identity came from a runtime session record, bridge selection, or was unavailable.

This is control-plane evidence about the model labels selected and recorded by the clients. It is not cryptographic proof of underlying weights or an audit of a provider's internal routing. models[] lists successful contributors, not every provider that received input, so it is not a data-egress audit.

Usage (MCP)

In Claude Code, just describe what you want reviewed. Claude Code will pick the right tool:

Plan review:

"Review this implementation plan before I start coding." "Check my plan for security issues and scalability risks."

Code review:

"Review the changes I just made." (Claude Code runs git diff and passes it) "Review this diff for bugs and security issues."

Pre-commit check:

"Run a pre-commit check on my staged changes." "Check if these changes are safe to commit."

Session continuity — pass the session_id from a plan review into a code review to maintain context across the full review lifecycle.

Standalone CLI

Run reviews directly from the terminal — no MCP setup required.

Pre-commit check (auto-captures staged changes):

npx codex-claude-bridge@latest review-precommit

Block commits on issues (CI-friendly, exits 2 on blockers):

npx codex-claude-bridge@latest review-precommit && git commit

Review a plan:

npx codex-claude-bridge@latest review-plan --plan plan.md

Review a diff:

git diff main | npx codex-claude-bridge@latest review-code --diff -

Review a branch or landed commits (no pasted diff, no scratch worktree):

npx codex-claude-bridge@latest review-code --base main            # main..HEAD
npx codex-claude-bridge@latest review-code --base v1.2.0 --head v1.3.0

Review another checkout or worktree:

npx codex-claude-bridge@latest review-precommit --cwd ../app/.worktrees/feature-x

--cwd picks the repository being reviewed: it decides where git captures from, which repository instruction files apply, and where the reviewer runs. Relative paths resolve against your current directory. It does not change how --plan, --diff, or --config are resolved — those stay relative to where you ran the command.

Add --json to any command for raw JSON output. Use --help to see all options.

Tools Reference

review_plan

Send an implementation plan for architectural/feasibility review.

Returns: { verdict, summary, findings[], session_id, models[], provenance }

review_code

Send a code diff for code review.

Returns: { verdict, summary, findings[], session_id, models[], provenance }, plus captured_from when the diff was auto-captured or taken from a base/head range.

Findings include file and line references when available.

review_precommit

Quick pre-commit sanity check. Auto-captures staged git changes by default.

Returns: { ready_to_commit, blockers[], warnings[], session_id, models[], provenance }, plus captured_from when the diff was auto-captured.

Choosing the directory to review (cwd)

One server can review several repositories. Pass cwd — an absolute path — and that directory decides everything about where the review happens:

• which repository auto_diff / review_precommit capture from,

• which .github/copilot-instructions.md and .github/instructions/*.instructions.md apply,

• which directory the reviewer subprocess itself runs in.

Omit cwd and the bridge uses the directory the MCP client launched the server in. That default is frequently not where you are working — a git worktree, a second checkout, or an agent driving work in another repository all end up somewhere else — which is exactly what cwd is for.

// review the worktree, not wherever the server happens to have been started
{ "cwd": "/Users/me/code/app/.worktrees/feature-x" }

Rules:

• Absolute only. A relative path would resolve against the server's directory, which is the confusion this parameter removes. ~ is not expanded.

• Per call. cwd is not stored on the session. Pass it again on every call, including resumes.

• Symlinks are fine — the path is canonicalized with realpath, so worktrees reached through a symlink work.

• A missing path, a broken symlink, a file, or a directory that cannot be read returns INVALID_INPUT before any reviewer is contacted.

• review_plan and explicit-diff reviews work in any readable directory. Auto-capture needs a git work tree: pointing it at a plain directory returns INVALID_INPUT rather than silently reviewing nothing.

• Capture is anchored at the repository root, so a subdirectory still reviews the whole repository — the same thing git diff does from a subdirectory.

The CLI takes the same option as --cwd <path>, where relative paths resolve against your shell's current directory. It does not rebase --plan, --diff, or --config, which stay relative to where you ran the command.

Where the diff came from

Auto-captured results (review_code without a diff, review_precommit without a diff) carry captured_from: the absolute directory the bridge ran git in — the repository root of the resolved cwd, or of the server's launch directory when you passed none. It is the answer to "which repository is this review actually about", and it is worth checking whenever a result surprises you: an empty result means "nothing staged there", not "nothing staged".

Empty auto-captures say so explicitly — No staged changes found in /path/to/repo — and git failures append capture attempted from "/path/to/repo". If captured_from is not the repository you meant, pass cwd, or supply the diff yourself:

git diff --staged | <your client's review_precommit with an explicit diff>

Explicit diffs never carry captured_from — even when the bridge resolved a repository for them — and the field is never persisted to review history or shown to the reviewer.

review_status

Check status of a review session.

Returns: { status, session_id, elapsed_seconds }

review_history

Query past reviews.

Returns: { reviews[], next_cursor }. Recent pages are newest-first; session pages are oldest-first. Each entry includes models plus model_metadata_status (recorded, legacy_unrecorded, or invalid). Legacy rows are never backfilled from today's defaults, and malformed stored metadata is returned as models: null.

Configuration

Create .reviewbridge.json in your project root to customize review behavior:

{
  "provider": "codex",
  "fallback": true,
  "model": "gpt-6-astra",
  "reasoning_effort": "medium",
  "timeout_seconds": 300,
  "max_chunk_tokens": 8000,
  "review_standards": {
    "plan_review": {
      "focus": ["architecture", "feasibility"],
      "depth": "thorough"
    },
    "code_review": {
      "criteria": ["bugs", "security", "performance", "style"],
      "require_tests": true
    },
    "precommit": {
      "auto_diff": true,
      "block_on": ["critical", "major"]
    }
  },
  "project_context": "Your project description and constraints."
}

All fields are optional. Missing fields use the defaults shown above. Large diffs are automatically split into chunks of approximately max_chunk_tokens tokens and reviewed sequentially. review_code and review_precommit results report chunks_reviewed (how many reviewer calls ran) and, when the diff was split, chunk_files — the files each chunk held, in order — so you can tell whether any single call saw two files together.

• provider — "codex" (default) or "gemini". Selects which backend reviews.

• mode — "failover" (default), "single", "deliberate", or "deliberate-deep". Picks how the two providers combine; see Provider failover and Deliberation. When unset it's derived from fallback.

• fallback — true (default) auto-fails-over to the other provider when the configured one is out of usage or unavailable. Set false (equivalently "mode": "single") for strict single-provider behavior.

• require_cwd — true (default) refuses an MCP review_code/review_precommit call that would auto-capture a diff without cwd, returning INVALID_INPUT instead of capturing from the server's launch directory (which, from a worktree or second checkout, is silently the wrong repository). Set false for a server that only ever serves the repository it was started in. Explicit diffs, review_plan, and the CLI are unaffected.

• reasoning_effort — Codex only. Gemini's effort is baked into its model name (e.g. "Gemini 3.8 Flash (High)"), so the field is ignored for Gemini.

• codex_path — absolute path to a codex binary for the Codex SDK to spawn (the CODEX_PATH env var works too; the config field wins). Normally unnecessary: when unset, the SDK uses its own bundled binary, and if that binary can't run the bridge auto-discovers a working system codex from your PATH and the usual install locations (~/.local/bin, /opt/homebrew/bin, /usr/local/bin), retries, and logs the substitution on stderr. Set it explicitly to pin a specific binary — an explicit path disables auto-discovery entirely.

Where the config is discovered

When the MCP server or CLI starts, it looks for .reviewbridge.json in this order. The first match wins; nothing is merged.

1. RB_CONFIG_PATH env var — if set, load exactly that file. Useful when the bridge is launched from a directory that isn't your project (e.g. an MCP host launches it from your home dir). Missing or unreadable file is a hard startup error so typos are surfaced immediately, not silently ignored.

2. Walk-up from the working directory — looks for .reviewbridge.json in the current directory, then each parent. The walk stops at the first .git boundary so a project nested inside an unrelated git repo doesn't accidentally inherit a parent project's config.

3. $HOME/.reviewbridge.json — a per-machine default. Drop one here to pin a model (e.g. {"model": "gpt-5.6-sol"}) for every project on the box without having to touch each one.

4. Built-in defaults — what you get if nothing is found anywhere.

A startup log line on stderr names the source ([codex-bridge] config source: project (/repo/.reviewbridge.json)) so you can confirm which file is in effect.

The CLI's --config <dir> flag is an explicit override: it looks only at <dir>/.reviewbridge.json and skips the cascade entirely (env vars and $HOME are not consulted in that mode).

Selected files must parse cleanly. Once a .reviewbridge.json is found, malformed JSON or schema-invalid values abort startup. The walk-up does not silently skip past a broken file to the next candidate — that would hide your typo and leave you running on defaults.

Model selection

model takes a concrete id, "latest", or a tier; each provider resolves its own default when the field is unset.

Tiers let a caller pick by difficulty or urgency instead of tracking model ids. Each provider maps a tier to its own model, and the tier carries across provider failover:

Rule of thumb for an agent: fast for a precommit check or a diff under a few hundred lines with no cross-file logic, max when the plan or diff touches concurrency, auth, data integrity, or a design you are unsure about, balanced otherwise. The tier name is reported back as requested in models, with the concrete id in resolved.

Codex — default gpt-6-astra. If Astra has not reached your account yet, pin gpt-5.6-sol:

Gemini — default resolves to the latest Flash via agy models. Effort is part of the model name:

"latest" resolves to the newest Flash for Gemini, or the SDK-pinned flagship for Codex. These are the models we document and recommend; the model field, the model tool parameter, and the --model CLI flag accept any trimmed, control-free selector up to 200 characters, so you can run others. For Gemini, an unrecognized model triggers a non-blocking stderr warning (agy may silently run a different one) — run agy models to see the live list.

Provider failover

When fallback is on (the default) and both providers are set up, a review that fails because the configured provider is out of usage or unavailable (rate-limited / usage cap, model not available on your tier, or not signed in) is automatically retried on the other provider. You'll see a one-line note on stderr:

[codex-bridge] codex unavailable (RATE_LIMITED); falling back to gemini

The result is tagged with the provider that actually served it ("provider": "gemini") and carries a failover block saying what happened, so a Gemini answer to a Codex request is never mistaken for the primary having served:

"failover": {
  "from": "codex",
  "error": "MODEL_ERROR: Model \"gpt-5.3-codex-spark\" was rejected, ...",
  "requested_model": "gpt-6-astra",
  "carried_model": "max"
}

requested_model is what the call asked for; carried_model is what the other provider was handed. A tier (max / balanced / fast) carries as-is, and a provider-specific id that is one of that provider's tier models is carried as its tier (gpt-6-astra → max, so Gemini answers with its Pro model rather than its Flash default). Any other id cannot be mapped: carried_model is null and the secondary resolves its own default. The models[] entry keeps the original requested selector either way. review_mode says which composition is configured; the presence of failover says one actually happened. Notes:

• Fresh reviews only. A resumed session lives in one provider's conversation store, so a session_id review is not failed over — start a fresh review on the other provider to continue.

• Data egress. Failover can send your diff to the other vendor (e.g. OpenAI → Google) when the primary is down. Set "fallback": false to disable this (also good for CI determinism).

• Failover never triggers on a bad diff or a malformed model response — only on genuine provider-unavailability.

Deliberation

"mode": "deliberate" sends review_plan and review_code to both providers independently, then returns where they agree vs diverge so the caller (Claude Code) can synthesize. Findings both providers flag are high-confidence; findings only one flags need a judgment call.

{ "provider": "codex", "mode": "deliberate" }

The result keeps the usual shape (a merged verdict/findings, worst-verdict wins) plus an additive deliberation block:

{
  "verdict": "reject",
  "findings": [
    /* deduped union of both providers */
  ],
  "deliberation": {
    "providers": ["codex", "gemini"],
    "verdicts": [
      { "provider": "codex", "verdict": "request_changes" },
      { "provider": "gemini", "verdict": "reject" }
    ],
    "agreement": "conflict", // agree | mixed | conflict
    "agreed": [
      /* findings BOTH flagged — high confidence */
    ],
    "divergent": [
      {
        "provider": "gemini",
        "finding": {
          /* only one flagged */
        }
      }
    ]
  }
}

Notes:

• Cost/egress: deliberation always runs both providers and sends the diff to both vendors — best for high-stakes reviews, not every precommit. review_precommit stays failover under this mode.

• Degrades gracefully: if one provider is out of usage, you get the other's review with deliberation.degraded set and deliberation.agreement: "degraded" (it subsumes failover).

• Resumed sessions deliberate too: passing a session_id resumes the review on the provider that owns that session while the other provider reviews fresh, then the two are combined — so plan→code lifecycles keep deliberating instead of silently dropping to one provider. The combined result keeps the resumed session's id.

• Per-call toggle: review_plan/review_code accept a deliberate boolean (CLI: --deliberate / --no-deliberate) that overrides the configured mode for a single call — true forces deliberation, false forces single-provider failover. Requesting deliberate: true under "mode": "single" returns an error (no second provider).

• review_mode on every result: every review result carries a review_mode field (single / failover / deliberate / deliberate-deep) naming the composition that actually ran, so the absence of a deliberation block is never ambiguous.

Deliberate-deep (cross-review round)

"mode": "deliberate-deep" is deliberation plus one more step: after both providers review, each divergent finding (one only one provider flagged) is handed to the other provider to adjudicate — confirm it's a real issue, dispute it as a false positive, or mark it unsure. Because providers word findings differently and cite different line numbers, semantically-identical issues often land in divergent rather than agreed; the cross-review round tells you which of those one-sided findings the other provider actually stands behind.

{ "provider": "codex", "mode": "deliberate-deep" }

Each divergent item gains an optional adjudication (the agreed findings and top-level shape are unchanged):

"divergent": [
  {
    "provider": "codex",
    "finding": { "severity": "major", "category": "Null safety", "file": "src/auth.ts", "line": 5, "description": "…" },
    "adjudication": { "by": "gemini", "verdict": "confirmed", "reason": "returns undefined for a header with no space" }
  }
]

Notes:

• verdict is confirmed (a real issue), disputed (a false positive here), or unsure (can't tell from the change). by is the provider that adjudicated — always the one that did not raise the finding.

• Top-level verdict is not folded back: under deliberate-deep the result's verdict still reflects both providers' independent reviews (worst-of-both). The per-finding adjudications are advisory input for your synthesis — the bridge does not recompute the verdict from them (ISS-015). A reject resting on findings the other provider disputed still reports reject; it's up to you to weigh the adjudications.

• Cost: adds up to two more provider calls per review (one per side that has divergent findings). Skipped entirely when there's nothing divergent. The cross-review subject is sliced to just the files the divergent findings touch, so it stays small even on large diffs.

• Best-effort: if a provider is out of usage or errors during the cross-review round, its side is simply left un-adjudicated and reported in deliberation.cross_review_failures — the deliberation result still returns.

Storage

Set REVIEW_BRIDGE_DB to persist review history and session state:

export REVIEW_BRIDGE_DB=~/.review-bridge.db

Defaults to reviews.db in the current directory. Set to :memory: for ephemeral storage.

Review execution is admitted before large inputs enter a provider: at most four logical reviews may run globally and only one may run for a given session_id. Excess work returns REVIEW_BUSY immediately. If durable outcome recording fails after a provider succeeds, the successful review is still returned with provenance.persistence: "memory_only" and a sanitized warning. Synthetic no-change/no-staged results use not_recorded and do not create or mutate sessions.

Troubleshooting

Error codes are provider-neutral. With fallback on (default), many of these auto-recover by retrying on the other provider — the messages below apply when there's no second provider set up or fallback is off.

SQLite native addon cannot load

Both disk-backed and in-memory review storage require better-sqlite3's native addon. If it is missing or incompatible with the MCP host's Node.js version or architecture, the server still starts and keeps serving reviews, but without any review storage: the startup diagnosis is logged once on stderr, review_history and review_status (for sessions this process is not running) answer STORAGE_UNAVAILABLE with that diagnosis, and every review result carries provenance.persistence: "not_recorded" with the diagnosis as its warning. Session resume works only within the running process. Switching REVIEW_BRIDGE_DB to :memory: cannot fix this. Ordinary database-file failures still fall back to memory after it successfully initializes.

After a Node.js upgrade or switch (nvm, Volta, Homebrew), the previously built addon no longer matches the host's ABI and fails with a NODE_MODULE_VERSION mismatch. Run npm rebuild better-sqlite3 in the affected installation with the new Node.js active, then reconnect.

A missing addon can follow an incomplete installation or disabled install scripts; the error alone does not identify the cause. ABI errors can also occur after changing Node.js versions.

1. Stop the bridge and use a terminal with the same Node.js version and architecture as the MCP host.

2. For an npx installation, locate the affected install root from the binding paths in the error: the directory immediately above node_modules (typically ~/.npm/_npx/<id>). For a local installation, use the project containing that node_modules directory.

3. In that directory, run npm rebuild better-sqlite3 --ignore-scripts=false and let it finish outside the MCP startup timeout. If it fails, resolve the reported prebuilt-binary download or native build prerequisite error before retrying. A fresh installation must also complete with install scripts enabled.

4. Restart the MCP connection after the rebuild succeeds.

The bridge does not rebuild dependencies or remove npm caches automatically. Reconnecting alone may reuse an incomplete npx installation.

Architecture

                                  ┌─ @openai/codex-sdk ──► OpenAI Codex
Claude Code ──MCP/CLI──► bridge ──┤
                          │       └─ agy subprocess ─────► Google Gemini
                      SQLite DB
                    (review history)

Both providers sit behind one ReviewBackend seam. Codex uses @openai/codex-sdk (which spawns codex exec internally; ChatGPT and API-key auth share the same path); Gemini wraps the agy --print --sandbox subprocess. A failover decorator wraps the two so an out-of-usage primary retries on the other.

src/
  index.ts          → Entry point (routes to MCP or CLI)
  mcp.ts            → MCP server startup
  server.ts         → Server setup, tool registration
  cli/              → Standalone CLI (Commander.js)
  tools/            → MCP tool handlers (5 tools)
  backends/         → Provider backends behind one seam: codex, gemini (agy),
                      a shared orchestrator, and the failover decorator
  codex/            → Prompts, Zod response schemas, shared types
  config/           → .reviewbridge.json loader
  storage/          → SQLite persistence (reviews, sessions)
  utils/            → Git diff, chunking, error types

Development

git clone https://github.com/AmirShayegh/codex-claude-bridge.git
cd codex-claude-bridge
npm install
npm test
npm run build

License

MIT