ReviewPilot

An MCP server that catches real bugs in your code before you open a PR — powered by OpenAI models.

It plugs into any MCP client (Claude Code, Cursor, etc.), reads your git changes, builds rich context from the repo, and returns structured, actionable findings focused on correctness, security, concurrency, and performance.

Quick start

Prerequisites

• Python 3.10+
• Git
• An OpenAI API key
• Optional: [ck](https://github.com/nickarino/ck-search) for semantic context

Setup

git clone <repo-url> review-pilot && cd review-pilot
export OPENAI_API_KEY=sk-...

Claude Code:

make setup-claude

Cursor:

make setup-cursor

Review the generated config.yaml and uncomment settings you want to override. The defaults are:

• model: gpt-5.3-codex
• review_passes: 3
• enable_validator_pass: true

That's it. Both commands install dependencies, register the MCP server, and add the skills.

Skills

Skill	What it does
/pr-check	Reviews your changes and summarizes findings — no code modifications
/pr-fix	Reviews your changes, then fixes actionable findings automatically

/pr-check

Runs a read-only review of your current changes (staged or branch diff). Lists all findings grouped by severity with file, line, and description. Use this to get a quick overview before opening a PR.

/pr-fix

Same review as /pr-check, but goes further — automatically fixes high and medium severity findings with high/medium confidence. Re-runs the review after fixing to confirm. Summarizes what was found, what was fixed, and what was skipped.

MCP Tools

The skills above use these tools under the hood. You can also call them directly:

Tool	What it does
review_diff	Reviews all commits on the current branch vs the base branch (base...HEAD)
review_staged	Reviews staged changes (git diff --cached)
health_check	Reports config status; optionally probes the OpenAI API

How it works

git changes ──► build context ──► model review ──► structured findings

1. Collect changes — computes the relevant diff (base...HEAD or --cached).
2. Build context — gathers key repo files (README, pyproject.toml, etc.), contents of changed files (bounded by size), and optional semantic search results from [ck](https://github.com/nickarino/ck-search).
3. Review — sends the diff + context to the configured OpenAI model. In multi-pass mode, the diff is shuffled across passes so different files get top attention each time.
4. Consolidate (optional) — a validator pass deduplicates and ranks findings across passes.

Each finding includes:

• Severity and confidence (high / medium / low)
• File and line reference
• Failure mode — what goes wrong and why
• Evidence path — entrypoint -> helper -> sink
• Suggested fix

Configuration

OPENAI_API_KEY must be set as an environment variable (or in a .env file at the project root). All other settings are configured in config.yaml.

Setting	Default	Description
OPENAI_API_KEY (env)	(required)	Your OpenAI API key
model	gpt-5.3-codex	Model to use for reviews
ck_bin	(auto-detected)	Path to the [ck](https://github.com/nickarino/ck-search) binary for semantic context enrichment
review_passes	3	Number of review passes over the diff
enable_validator_pass	true	Consolidate multi-pass findings into a deduplicated final review

For faster, cheaper reviews set review_passes: 1 and enable_validator_pass: false. For deeper reviews on critical changes, try review_passes: 8 along with enable_validator_pass: true.

Make targets

Command	What it does
make check	Preflight checks (Python, git, pip, OPENAI_API_KEY)
make install	Run checks + install dependencies (attempts ck install; non-fatal)
make install-ck	Install optional ck binary for semantic context
make start	Run the MCP server standalone
make setup-claude	Install + configure Claude Code (MCP server + skills)
make setup-cursor	Install + configure Cursor (MCP server + rules)
make configure-claude	Configure Claude Code only (skip install)
make configure-cursor	Configure Cursor only (skip install)

Manual setup

If you prefer not to use make, add this to your MCP client config:

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "review-pilot": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "review_pilot"],
      "cwd": "/absolute/path/to/review-pilot",
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "review-pilot": {
      "command": "python3",
      "args": ["-m", "review_pilot"],
      "cwd": "/absolute/path/to/review-pilot",
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

Then copy the skills manually:

• Claude Code: symlink skills/claude-code/* into ~/.claude/skills/
• Cursor: copy skills/cursor/*.md into ~/.cursor/rules/ as .mdc files

Troubleshooting

Problem	Fix
OPENAI_API_KEY is not set	export OPENAI_API_KEY=sk-..., set it as an env var in your shell's rc file or set it in the MCP client env block
ck not found	Run make install-ck, set CK_BIN to the absolute path, or leave it unset to skip semantic context. We highly recommend installing this dependency for higher quality reviews.
No changes reviewed	Make sure you have staged changes (review_staged) or a branch diff (review_diff)
Reviews are slow or expensive	Lower REVIEW_PASSES or set ENABLE_VALIDATOR_PASS=false