| name | ai-review |
| description | Get AI code review from a second model (Gemini/OpenAI) mid-session via CLI. Use when asked to review code, get a second opinion, check quality, or verify implementation — especially in unfamiliar stacks. Triggers on /ai-review, "review this", "get a second opinion", "check with another model". |
| globs | [] |
| license | MIT |
| metadata | {"author":"eins78","repo":"https://github.com/eins78/agent-skills","version":"0.0.3"} |
| compatibility | Claude Code, Cursor |
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
- Get a key from Google AI Studio
- 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.
- Configure the gemini CLI to use API key auth:
- 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.
- 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.
${CLAUDE_SKILL_DIR}/scripts/review.sh
${CLAUDE_SKILL_DIR}/scripts/review.sh --staged
${CLAUDE_SKILL_DIR}/scripts/review.sh path/to/file1.swift path/to/file2.swift
${CLAUDE_SKILL_DIR}/scripts/review.sh --branch
REVIEW_BASE_BRANCH=origin/main ${CLAUDE_SKILL_DIR}/scripts/review.sh --branch
${CLAUDE_SKILL_DIR}/scripts/review.sh --context "SwiftUI app, iOS 18+, Swift 6" path/to/file.swift
${CLAUDE_SKILL_DIR}/scripts/review.sh --plan PLAN.md path/to/file.swift
${CLAUDE_SKILL_DIR}/scripts/review.sh --no-context --staged
Step 3: Act on Feedback
After receiving the review:
- Address any ERROR-severity issues immediately
- Consider WARNING items — fix unless there's a good reason not to
- INFO items are suggestions — use judgment
- 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):
- Implementation plan — first found of:
--plan flag, PLAN.md at repo root, most recent .claude/plans/*.md
- Project instructions — first found of:
CLAUDE.md, GEMINI.md, AGENTS.md at repo root
- 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:
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.
