Skip to content

CODEX_GEMINI_REVIEW_GUIDE.md

Latest commit

 

History

History
249 lines (179 loc) · 9.25 KB

CODEX_GEMINI_REVIEW_GUIDE.md

File metadata and controls

249 lines (179 loc) · 9.25 KB

Codex + Gemini Reviewer Guide

Run ARIS with:

  • Codex as the main executor
  • Gemini as the reviewer
  • the local gemini-review MCP bridge as the transport layer
  • the direct Gemini API as the default reviewer backend

This guide is additive to the upstream Codex-native path. It does not replace skills/skills-codex/.

Architecture

  • Base skill set: skills/skills-codex/
  • Reviewer override layer: skills/skills-codex-gemini-review/
  • Reviewer bridge: mcp-servers/gemini-review/

The install order matters:

  1. install skills/skills-codex/*
  2. install skills/skills-codex-gemini-review/*
  3. register gemini-review MCP

Install

git clone https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep.git
cd Auto-claude-code-research-in-sleep

mkdir -p ~/.codex/skills
cp -a skills/skills-codex/* ~/.codex/skills/
cp -a skills/skills-codex-gemini-review/* ~/.codex/skills/

mkdir -p ~/.codex/mcp-servers/gemini-review
cp mcp-servers/gemini-review/server.py ~/.codex/mcp-servers/gemini-review/server.py
cp mcp-servers/gemini-review/README.md ~/.codex/mcp-servers/gemini-review/README.md
codex mcp add gemini-review --env GEMINI_REVIEW_BACKEND=api -- python3 ~/.codex/mcp-servers/gemini-review/server.py

Recommended credential file:

mkdir -p ~/.gemini
cat > ~/.gemini/.env <<'EOF'
GEMINI_API_KEY="your-key"
EOF
chmod 600 ~/.gemini/.env

The bridge auto-loads ~/.gemini/.env if present.

Why direct API is the default

  • This path is designed to maximize reuse of the original ARIS reviewer-aware skills while minimizing skill changes.
  • The gemini-review bridge preserves the same review / review_reply / review_start / review_reply_start / review_status contract used by the existing Claude-review overlay.
  • Using the direct Gemini API removes the extra local CLI hop and keeps the reviewer path closer to the API-backed integrations already used elsewhere in ARIS.

Access Notes

  • Google AI Studio / Gemini API has a free tier in eligible countries; this does not require a Gemini Advanced / Google One AI Premium subscription.
  • Free-tier model availability and rate limits change over time, so do not treat any single quota number or older model example as permanent.
  • On the free tier, prompts and responses may be used to improve Google's products; do not position this path as suitable for sensitive data unless the user has reviewed the current official terms.
  • Official references:

Optional CLI fallback

The intended path is direct API. If you explicitly need Gemini CLI instead:

codex mcp remove gemini-review
codex mcp add gemini-review --env GEMINI_REVIEW_BACKEND=cli -- python3 ~/.codex/mcp-servers/gemini-review/server.py

That fallback is available, but it is not the primary path for this guide.

Verify

  1. Check MCP registration:
codex mcp list
  1. Check that your Gemini API key file exists:
test -f ~/.gemini/.env && echo "Gemini env file found"
  1. Start Codex in your project:
codex -C /path/to/your/project

Troubleshooting

If the default API model returns temporary free-tier 429 responses in your current window, keep the same bridge and override only the reviewer model:

codex mcp remove gemini-review
codex mcp add gemini-review --env GEMINI_REVIEW_BACKEND=api --env GEMINI_REVIEW_MODEL=gemini-flash-latest -- python3 ~/.codex/mcp-servers/gemini-review/server.py

This does not change the ARIS reviewer contract or skill overlay shape. It only changes the Gemini API model used behind the same local gemini-review bridge.

Validation Summary

This path was validated in two layers:

  • Full overlay coverage check: all 15 predefined reviewer-aware Codex skills overridden by skills/skills-codex-gemini-review/ were checked to confirm they point at gemini-review and no longer depend on the old reviewer transport.
  • Runtime bridge check: the local gemini-review MCP bridge was exercised with:
    • review
    • review_reply
    • review_start
    • review_reply_start
    • review_status
    • imagePaths multimodal review for local images
  • Representative Codex-side smoke tests: we ran the overlay on a private, non-public research repository and confirmed that real Codex executions reached the Gemini reviewer path for representative tasks in research review, idea generation, and paper-planning style workflows.

What passed:

  • direct API review returned valid reviewer text
  • async review jobs completed and could be resumed through review_status
  • follow-up review rounds worked with persisted thread state
  • local-image review worked through imagePaths
  • the runtime-tested Codex skill paths successfully loaded the Gemini overlay and issued real gemini-review tool calls

What we observed:

  • Gemini free-tier access is practical for this reviewer path, but bursty test loops can still trigger temporary 429 rate-limit responses
  • rate-limit behavior is model-dependent; current API model surfaces should be checked in AI Studio / ListModels, not inferred from older quota tables
  • in a later retry on the same setup, the direct API bridge completed sync review, async review_start -> review_status, and threaded review_reply_start -> review_status successfully with GEMINI_REVIEW_MODEL=gemini-flash-latest
  • those 429 responses behaved like short-window burst limits, not a sign that the integration itself was broken
  • long synchronous reviewer calls can still hit host-side MCP tool timeouts, so the async review_start / review_reply_start + review_status flow remains the recommended default for long prompts

This is why the bridge exposes both sync and async tools, while the reviewer-aware skill overlays prefer the async path for long reviews.

What gets overridden

The overlay replaces the predefined reviewer-aware Codex skills:

  • idea-creator
  • idea-discovery
  • idea-discovery-robot
  • research-review
  • novelty-check
  • research-refine
  • auto-review-loop
  • grant-proposal
  • paper-plan
  • paper-figure
  • paper-poster
  • paper-slides
  • paper-write
  • paper-writing
  • auto-paper-improvement-loop

Everything else still comes from the upstream skills/skills-codex/ package.

Core 8 vs Runtime 15

There are two equally correct ways to describe the scope of this path:

  • Core 8: the direct one-to-one reviewer overlay set that aligns with the existing Claude-review path
  • Runtime 15: the full reviewer-aware Codex skill surface that is routed to Gemini in the current installed skill set

The core 8 are:

  • research-review
  • novelty-check
  • research-refine
  • auto-review-loop
  • paper-plan
  • paper-figure
  • paper-write
  • auto-paper-improvement-loop

These are the skills that most directly mirror the earlier Claude-review overlay structure and reviewer contract.

The additional 7 reviewer-aware skills routed to Gemini are:

  • idea-creator
  • idea-discovery
  • idea-discovery-robot
  • grant-proposal
  • paper-writing
  • paper-slides
  • paper-poster

So the practical summary is:

  • the core mechanism still tracks the same 8-skill overlay pattern as the Claude route
  • the current runtime reviewer surface is broader, reaching 15 skills in total

This is why the diff is larger without changing the underlying reviewer contract shape.

Direct Consumers vs Wrappers

Within those 15 skills, there are two categories:

  • 12 direct consumers that call mcp__gemini-review__review_start / review_reply_start / review_status themselves:
    • research-review
    • novelty-check
    • research-refine
    • auto-review-loop
    • paper-plan
    • paper-figure
    • paper-write
    • auto-paper-improvement-loop
    • idea-creator
    • grant-proposal
    • paper-slides
    • paper-poster
  • 3 wrappers that mainly orchestrate downstream reviewer-aware sub-skills and pass REVIEWER_MODEL=gemini-review through:
    • idea-discovery
    • idea-discovery-robot
    • paper-writing

This matters for validation: you do not need to fully complete all 15 workflows to validate the reviewer transport. A combination of full structural checks, bridge runtime checks, and representative direct-consumer / wrapper smoke tests is enough to validate the PR-level integration logic.

Async reviewer flow

For long paper or project reviews, use:

  • review_start
  • review_reply_start
  • review_status

Why: even on the direct API path, long synchronous reviewer calls can still hit host-side MCP tool timeouts. The async review* flow keeps the original reviewer-aware skills usable without changing their behavior.

Project config

No special project config file is required for this path.

  • keep using your existing CLAUDE.md
  • keep your current project layout
  • only switch the installed Codex skill files and MCP registration

Maintenance

Keep this path intentionally narrow:

  • reuse skills/skills-codex/* unchanged
  • only override the reviewer-aware skills in skills/skills-codex-gemini-review/*
  • keep mcp-servers/gemini-review/server.py focused on the review* compatibility contract
  • when a skill needs poster PNG review, pass local imagePaths through the direct Gemini API backend instead of inventing a second bridge
⚡