ai-pr-review

AI-powered code reviewer for git pull requests. Runs locally, reviews your branch diff using Gemini or Claude, and prints findings to your terminal.

Install

npm install -g ai-pr-review

Or run without installing:

npx ai-pr-review

Quick start

1. Get an API key

• Gemini (free tier, 1,500 req/day): aistudio.google.com
• Anthropic (paid): console.anthropic.com

2. Set your key

export GEMINI_API_KEY=your_key_here
# or
export ANTHROPIC_API_KEY=your_key_here

3. Run on your branch

cd your-project
git checkout your-feature-branch
ai-pr-review

That's it. It diffs your branch against main and prints the review.

Options

--base <branch>       Base branch to diff against        [default: main]
--provider <name>     AI provider: gemini | anthropic    [default: gemini]
--model <model>       Override the default model
--fail-on <severity>  Exit 1 if issues found at severity [default: major]
--ci                  CI mode: JSON output + exit codes
--post                Post review as GitHub PR comment
--pr <number>         GitHub PR number (skips auto-detection)
--exclude <patterns>  Comma-separated globs to skip
--config <path>       Path to .prreview.json
--debug               Verbose logging

Config file

Drop a .prreview.json in your repo root to avoid typing flags every time:

{
  "provider": "gemini",
  "baseBranch": "main",
  "failOnSeverity": "major",
  "excludePatterns": ["**/*.lock", "**/dist/**"],
  "customInstructions": "This is a TypeScript project. Focus on type safety."
}

All config options

| Field | Type | Default | Description | | -------------------- | ------------------------------------ | -------------------- | -------------------------------------------- | | provider | gemini \| anthropic | gemini | AI provider | | model | string | provider default | Override model | | baseBranch | string | main | Branch to diff against | | excludePatterns | string[] | ["**/*.lock", ...] | Glob patterns to skip | | failOnSeverity | critical \| major \| minor \| none | major | Exit code 1 threshold | | postToGitHub | boolean | false | Post review to GitHub PR | | githubRepo | string | — | Repo in "owner/repo" format (for --post) | | ciMode | boolean | false | JSON output mode | | customInstructions | string | — | Extra instructions for the AI | | reviewFocus | string[] | — | Focus areas: security, correctness, etc. |

Config priority (highest wins)

CLI flags > environment variables > .prreview.json > built-in defaults

Environment variables

| Variable | Description | | ----------------------- | ---------------------------------------------------- | | GEMINI_API_KEY | Required when using Gemini | | ANTHROPIC_API_KEY | Required when using Anthropic | | GITHUB_TOKEN | Required for --post (needs repo + pull_requests scopes) | | PRREVIEW_GITHUB_REPO | Repo in owner/repo format — required for --post | | PRREVIEW_PR_NUMBER | Manually set PR number (skips auto-detection) | | PRREVIEW_PROVIDER | Override provider | | PRREVIEW_MODEL | Override model | | PRREVIEW_BASE_BRANCH | Override base branch | | PRREVIEW_POST | Set to true to enable GitHub posting | | CI=true | Auto-enables CI mode |

GitHub posting setup

To post reviews directly onto your PR:

1. Create a GitHub token Go to github.com/settings/tokens/new and create a token with repo and pull_requests scopes.

2. Set env vars

export GITHUB_TOKEN=your_token_here
export PRREVIEW_GITHUB_REPO=your-org/your-repo

3. Run with --post

ai-pr-review --post

The tool auto-detects the open PR for your current branch. Or pass --pr 42 to specify manually.

Exit codes

| Code | Meaning | | ---- | ------------------------------------------------- | | 0 | Review done, no issues at/above failOnSeverity | | 1 | Issues found at/above failOnSeverity | | 2 | Tool error (bad config, git missing, API failure) |

CI usage

# GitHub Actions example
- name: Review PR
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    PRREVIEW_GITHUB_REPO: ${{ github.repository }}
  run: npx ai-pr-review --ci --fail-on major --post

License

MIT