ai-review

AI Code Review

Request code reviews from a second AI model mid-session via CLI.

Prerequisites

• gemini CLI installed (run ${CLAUDE_SKILL_DIR}/scripts/install-dependencies.sh)
• Auth: either GEMINI_API_KEY env var (recommended — see "Paid API" below) or Google Account OAuth (gemini interactively once)
• Optional: codex CLI for OpenAI reviews: brew install codex

CRITICAL: Never Skip Reviews

Quality over speed. When a review is requested, you MUST wait for the result. Do NOT:

• Skip the review because of rate limits or timeouts
• Proceed without the review and say "we can review later"
• Substitute your own review instead of calling the external model

The gemini CLI handles rate limit retries automatically. If the script exits with a timeout (exit code 2), ask your human partner for help — do not silently continue.

Rate Limits (Free Tier — Google Account Auth)

Metric	Limit
Requests per minute	60 RPM
Requests per day	1,000 RPD
Capacity (tokens/time)	Very low — the real bottleneck
Model	Auto-selected by Google (upgrades over time)
Cost	$0

Important: The RPM/RPD limits are rarely the issue. Google also enforces a capacity quota (total tokens processed per rolling time window) that is much more restrictive. Large review payloads (code + auto-context) can exhaust this quota in just a few requests, triggering a TerminalQuotaError with a multi-hour reset (typically 1-3 hours). This is especially tight on newer auto-selected models (e.g., Gemini 2.5 Pro).

To reduce quota pressure:

• Use --no-context for small/focused reviews to cut token usage
• Split large reviews into smaller chunks
• Use a paid API key to avoid capacity limits entirely (see below)

The CLI retries automatically on per-minute rate limit hits (resets in seconds). The capacity quota does NOT retry — it requires waiting for the reset window. The script has a 1-hour timeout — if exceeded, it aborts and you should ask the user for help.

Paid API (Recommended for Regular Use)

The free tier's capacity quota makes it impractical for more than a few reviews per session. A paid API key removes this bottleneck at minimal cost.

Setup

1. Get a key from Google AI Studio
2. Enable billing on the associated Google Cloud project — without billing, the API key still uses free-tier capacity limits (the same bottleneck as OAuth). In AI Studio: Settings → Billing, or in the Google Cloud Console.
3. Configure the gemini CLI to use API key auth:

   # Set auth type in gemini settings (~/.gemini/settings.json)
   # Run gemini interactively once — it will prompt to select auth method.
   # Choose "Gemini API Key" when prompted.
   

4. Set the environment variable:

   export GEMINI_API_KEY="your-key-here"
   

   Add this to your shell profile so new shells pick it up. If you're in an already-running session (e.g., Claude Code), you'll need to source the file or restart the session.
5. Verify it works: gemini -p "hello" — should respond without OAuth prompts or quota errors.

Cost Estimate (Gemini 2.5 Pro)

	Tokens	Cost
Input per review (context + diff)	~8-12K	~$0.01-0.015
Output per review	~1-2K	~$0.01-0.02
Total per review		~$0.02-0.04

Usage level	Reviews/month	Est. cost
Light (few/week)	~20	~$0.50
Moderate (few/day)	~60	~$1.50
Heavy (many/day)	~150	~$4.00

Tracking Usage

• AI Studio → Dashboard → Usage tab (requests, tokens, costs)
• Google Cloud Console → APIs & Services → Dashboard → "Generative Language API"
• Billing Reports → group by SKU for per-model breakdown
• Tip: Create multiple keys in the same project to separate ai-review usage from interactive gemini CLI use

How to Use

Step 1: Determine What to Review

Choose based on context:

Situation	What to send
Just wrote code	The specific files changed
Mid-feature	git diff (unstaged changes)
Before commit	git diff --cached (staged changes)
Branch review	git diff main...HEAD
Specific concern	Single file or function

Step 2: Run the Review

Use the review script at ${CLAUDE_SKILL_DIR}/scripts/review.sh — this path resolves to the skill's own directory regardless of the current working directory. Never use ./scripts/review.sh (that's relative to CWD and will fail in other repos). Never pipe code directly to gemini or codex — always use the review script.

# Review unstaged changes (default)
${CLAUDE_SKILL_DIR}/scripts/review.sh

# Review staged changes
${CLAUDE_SKILL_DIR}/scripts/review.sh --staged

# Review specific files
${CLAUDE_SKILL_DIR}/scripts/review.sh path/to/file1.swift path/to/file2.swift

# Review branch diff vs main
${CLAUDE_SKILL_DIR}/scripts/review.sh --branch

# Review branch vs remote (when working on main directly)
REVIEW_BASE_BRANCH=origin/main ${CLAUDE_SKILL_DIR}/scripts/review.sh --branch

# Add extra context string for better reviews
${CLAUDE_SKILL_DIR}/scripts/review.sh --context "SwiftUI app, iOS 18+, Swift 6" path/to/file.swift

# Review with a specific plan file
${CLAUDE_SKILL_DIR}/scripts/review.sh --plan PLAN.md path/to/file.swift

# Skip auto-context (only send the code/diff)
${CLAUDE_SKILL_DIR}/scripts/review.sh --no-context --staged

Step 3: Act on Feedback

After receiving the review:

1. Address any ERROR-severity issues immediately
2. Consider WARNING items — fix unless there's a good reason not to
3. INFO items are suggestions — use judgment
4. If the review raises questions you're unsure about, discuss with the user

Handling Failures

Exit code	Meaning	Action
0	Success	Act on review feedback
1	No code to review / bad args	Check arguments
2	Timeout (>1 hour blocked)	Ask user for help — do not skip the review

Auto-Context

The review script automatically prepends project context to every review so the reviewer understands conventions, architecture, and intent. No manual "Code Review Context" section needed in CLAUDE.md.

Included automatically (in order):

1. Implementation plan — first found of: --plan flag, PLAN.md at repo root, most recent .claude/plans/*.md
2. Project instructions — first found of: CLAUDE.md, GEMINI.md, AGENTS.md at repo root
3. File tree — repo structure at depth 3

Use --no-context to skip this (e.g., for very large payloads).

The --context flag adds an additional inline context string on top of the auto-context.

Provider Configuration

Default provider is gemini. Override per-session:

# Use OpenAI instead
REVIEW_PROVIDER=codex ${CLAUDE_SKILL_DIR}/scripts/review.sh

Important Notes

• Reviews are advisory — the second model may have false positives
• Large diffs (>50KB) may be truncated. Split into smaller reviews if needed.
• The review model runs in prompt mode (-p) and cannot browse the repo. Project context is auto-included to compensate — see "Auto-Context" above.