🤖 AI Code Reviewer

Multi-agent code review system that orchestrates multiple LLMs to produce comprehensive, high-quality code reviews.

---

Overview

AI Code Reviewer takes a different approach to automated code review: instead of relying on a single AI model, it orchestrates multiple specialized agents that review code from different perspectives (security, performance, architecture, etc.) and combines their findings into a unified, confidence-scored review.

Key Features

• 🔀 Multi-Agent Architecture: Run 2-5+ LLM agents in parallel, each with specialized focus
• 🎯 Consensus-Based Scoring: Findings are weighted by how many agents agree
• 🔑 Single API Key: All models (Claude, GPT-4, etc.) accessed via Cursor API
• 🐙 GitHub Integration: Automatic PR reviews via webhooks
• 📊 Actionable Output: Prioritized findings with suggested fixes

---

Quick Start

# Install
pip install ai-code-reviewer

# Configure - Only 2 API keys needed!
# Cursor API provides unified access to Claude, GPT-4, and other models
export CURSOR_API_KEY=cur_...
export GITHUB_TOKEN=ghp_...

# Review a GitHub PR
ai-reviewer review-pr calimero-network/core 123

# Review a local diff
git diff main | ai-reviewer review --output markdown

---

How It Works

All LLM agents access Claude, GPT-4, and other models through Cursor's unified API:

• ✅ Single API key for all models
• ✅ Consistent interface across different LLMs
• ✅ Codebase context for pattern-aware reviews

                            PR Diff
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│              Cursor API (Unified LLM Gateway)                 │
│                                                               │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐       │
│   │   Claude    │   │    GPT-4    │   │   Claude    │       │
│   │ (Security)  │   │(Performance)│   │ (Patterns)  │       │
│   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘       │
│          │                 │                 │               │
│          └─────────────────┼─────────────────┘               │
│                            ▼                                 │
│   ┌──────────────────────────────────────────────────────┐  │
│   │                Review Aggregator                      │  │
│   │  • Cluster similar findings                           │  │
│   │  • Compute consensus scores                           │  │
│   │  • Rank by severity × agreement                       │  │
│   └──────────────────────────────────────────────────────┘  │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
              Consolidated Review (GitHub / JSON / MD)

---

Configuration

Create config.yaml:

# Single Cursor API key for all LLM models
cursor:
  api_key: ${CURSOR_API_KEY}

# GitHub integration
github:
  token: ${GITHUB_TOKEN}  # or PAT for thread resolution (see below)

# Agents - different models, same Cursor API
agents:
  - name: security-reviewer
    model: claude-4.5-opus-high-thinking
    focus_areas: [security, architecture]

  - name: performance-reviewer
    model: gpt-5.2
    focus_areas: [performance, logic]

  - name: patterns-reviewer
    model: claude-4.5-opus-high-thinking
    focus_areas: [consistency, patterns]
    include_codebase_context: true

orchestrator:
  timeout_seconds: 120
  min_agents_required: 2

---

CLI Commands

# Review Commands
ai-reviewer review-pr <owner/repo> <pr-number>  # Review GitHub PR
ai-reviewer review --diff <file>                 # Review local diff
ai-reviewer review --commit <sha>                # Review specific commit

# Server Commands
ai-reviewer serve --port 8080                    # Start webhook server

# Configuration
ai-reviewer config validate                      # Check configuration
ai-reviewer config show                          # Show active config

# Agents
ai-reviewer agents list                          # List available agents
ai-reviewer agents test <type>                   # Test single agent

---

Output Example

## 🤖 AI Code Review

**Reviewed by 3 agents** | Consensus score: 87%

### 🔴 Critical (1)

**SQL Injection** in `auth/login.py:45` | 3/3 agents ✓

> User input interpolated into SQL query

### 🟡 Warning (2)

**Missing rate limiting** | 2/3 agents
**Inefficient O(n²) loop** | 2/3 agents

### 💡 Suggestions (3)

- Add type hints to `process_user()`
- Extract magic number to constant
- Add docstring to `AuthHandler`

---

Repository Configuration

Add .ai-reviewer.yaml to your repo for custom settings:

# Ignore generated files
ignore:
  - "**/*.generated.rs"
  - "**/vendor/**"

# Custom instructions for agents
agents:
  - name: security-reviewer
    custom_prompt_append: |
      This is a Rust codebase using eyre for errors.
      Flag all unwrap() calls.

# Review policy
policy:
  require_human_review_for: [security]
  block_on_critical: true

---

GitHub Actions Setup

Basic Setup (GITHUB_TOKEN)

The default GITHUB_TOKEN provided by GitHub Actions works for most features:

• ✅ Posting reviews and comments
• ✅ Adding reactions
• ✅ Posting "Resolved" replies
• ❌ Resolving review threads (requires PAT)

Full Features (Classic Personal Access Token)

To enable automatic thread resolution when issues are fixed, use a Classic PAT (not Fine-grained):

⚠️ Important: Fine-grained PATs do NOT support the resolveReviewThread GraphQL mutation. You must use a Classic PAT with repo scope.

1. Create a Classic Personal Access Token with:

   • Note: ai-code-reviewer
   • Expiration: 90 days (or custom)
   • Scopes: ✅ repo (Full control of private repositories)

2. Add the PAT as a repository secret named GH_PAT:

   Settings → Secrets and variables → Actions → New repository secret
   Name: GH_PAT
   Value: ghp_xxxxxxxxxxxxxxxxxxxx
   

3. The workflow automatically uses GH_PAT if available (falls back to GITHUB_TOKEN).

Why Classic PAT? GitHub's GraphQL resolveReviewThread mutation requires:

• User-level authentication (not app/integration tokens)
• Classic PAT with repo scope (Fine-grained PATs return "Resource not accessible")

Without a Classic PAT, the reviewer will still post "✅ Resolved" replies, but threads won't collapse automatically in the GitHub UI.

---

Development

# Clone
git clone https://github.com/calimero-network/ai-code-reviewer
cd ai-code-reviewer

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linters
ruff check .
mypy src/

---

AI Rules & Documentation

This repository is designed to be AI-friendly with structured documentation that helps AI agents understand and work with the codebase.

For AI Assistants (Cursor, Claude, etc.)

.ai/                 # AI context, rules & automation
├── context.md         # Fast codebase overview (read first!)
├── doc-bot.md         # Documentation bot instructions
├── prompts/           # Reusable AI prompts
└── rules/             # Detailed rules per module
    ├── architecture.md  # High-level design & invariants
    ├── agents.md        # Agent module patterns
    ├── orchestrator.md  # Orchestration rules
    ├── github.md        # GitHub integration patterns
    ├── models.md        # Data model conventions
    └── conventions.md   # Coding style guide

Quick Start for AI Agents

1. Read .ai/context.md for a fast overview
2. Check .ai/rules/<module>.md for the specific module you're working on
3. Follow patterns in .ai/rules/conventions.md

Documentation Bot

PRs that change source code automatically trigger a documentation bot that:

• Analyzes which docs might need updates
• Posts suggestions as PR comments
• Helps keep documentation in sync with code

Configure via .ai-reviewer.yaml in the repo root.

---

Related Projects

• ai-bounty-hunter - Automatic bounty fixing
• pr-agent - Single-agent PR reviews
• SWE-agent - GitHub issue automation

---

License

MIT License - see LICENSE for details.

---

_{Built with ❤️ by Calimero Network}