AI Code Review Assistant

🤖 World's best desktop code review tool powered by AI.

Features

Core Capabilities

🔍 Smart Code Analysis - AI-powered code review with Pydantic AI
🤖 Multiple AI Providers - Support for OpenAI, Anthropic, Google, Mistral, Groq, and more
🌐 Multi-Platform - Works with GitHub, GitLab, Bitbucket, Azure DevOps
⚡ Temporal Workflows - Durable, long-running review orchestration
🎨 Beautiful Web UI - Modern, responsive interface with real-time streaming results
👀 Preview Mode - Review AI suggestions in UI before posting to GitHub
✋ Manual Approval - Only post to GitHub when you're ready
🔒 Privacy-First - Code stays on your machine
📝 Customizable Rules - Multi-level configuration (global, repo, file, PR)
⚙️ AI Configuration UI - Configure providers, models, API keys, and review settings
🔑 Secure API Key Storage - Store API keys securely (file-based with restricted permissions)

🚀 Advanced Analysis (World-Class Features)

🧠 Semantic Code Indexing - Tree-sitter-based AST parsing for accurate function/class extraction
🔎 Vector Search - ChromaDB-powered semantic similarity search across codebases
📊 Blast-Radius Impact Analysis - Symbol-level dependency graph (calls, inheritance, test coverage) with risk scoring; surfaces which functions, files, and tests a change affects, fed into every review by default
🎯 Context-Aware Reviews - AI leverages similar code patterns from your repository
🗂️ Smart Caching - Repository-level indexing reused across all PRs
📈 Incremental Updates - Only analyze changed files, not entire repos
🌳 Multi-Language Support - Python, JavaScript, TypeScript, Go, Rust (more coming)

🎮 Workflow Control Features

⏸️ Pause/Resume - Pause long-running indexing workflows and resume later
⏹️ Cancel - Gracefully stop workflows with automatic cleanup
🛑 Terminate - Immediately stop workflows (for emergencies)
🗑️ Purge - Delete ALL indexed data for a repository (ChromaDB, FalkorDB, cache)
🔄 Reindex - Force a complete rebuild of repository index
⚡ Parallel Indexing - Index multiple repositories simultaneously with per-job progress tracking

📊 Architecture Diagrams

🏗️ Auto-Generated Diagrams - AI generates Mermaid architecture diagrams from your code
📈 Dependency Visualization - See module relationships and data flow
🧩 Component Detection - Identifies services, databases, APIs, workers
🎨 Interactive Rendering - View, expand, and regenerate diagrams in the UI
⚡ Parallel Generation - Generate diagrams for multiple repos simultaneously
📊 Per-Repo Progress - Individual progress tracking for each generation

💬 Multi-Repository Chat (NEW!)

🤖 Conversational AI - Chat with your code across multiple repositories
🔍 RAG-Powered Answers - Responses backed by actual code from your repos
📝 Source Citations - Every answer includes file paths and line numbers
🌐 Web Search - Optionally search external docs, CVEs, and best practices
🔄 Streaming Responses - Real-time streaming with typing indicators
💡 Follow-Up Suggestions - AI suggests relevant next questions
📊 Confidence Scores - Know how certain the AI is about each answer

🧠 Multi-Agent Architecture

🔒 Security Agent - OWASP-focused vulnerability detection with CVE lookup
📖 Explainer Agent - Clear code explanations with analogies and diagrams
🐛 Bug Finder Agent - Deep edge case and bug detection
🔧 Refactoring Agent - SOLID-based improvement suggestions
🏗️ Architecture Agent - System design analysis
⚖️ Comparison Agent - Cross-repo implementation comparison
🌐 Web Search Agent - External documentation and CVE lookup

🔍 Multi-Agent PR Review (NEW!)

🤖 Parallel Specialist Analysis - Multiple agents analyze code simultaneously
🔀 Adaptive Selection - Automatically picks relevant agents per file type
📋 Deduplication - Merges overlapping findings from different agents
📊 Severity Ranking - Critical issues surfaced first
👁️ Transparency - See which agents found each issue
🎯 Configurable - Enable/disable specific agents per review

Quick Start with Docker (Recommended) 🐳

The easiest way to get started - everything in one command!

# 1. Clone and enter directory
git clone https://github.com/yourusername/code-review.git
cd code-review

# 2. Set up environment
cp .env.example .env
# Edit .env and add your tokens:
# - GITHUB_TOKEN (required)
# - OPENAI_API_KEY or ANTHROPIC_API_KEY (choose your AI provider)
# - AI_PROVIDER (openai or anthropic)
# - AI_MODEL (e.g., gpt-4o or claude-3-5-sonnet-20241022)

# 3. Start everything!
./start-docker.sh

# Or manually:
docker compose up --build

That's it! Open http://localhost:8888 and start reviewing!

What gets started:

✅ Web UI + API Server (port 8888)
✅ Temporal Worker (background)
✅ Temporal Server (orchestration)
✅ PostgreSQL (database)
✅ ChromaDB (vector database - port 8100)
✅ FalkorDB (graph database - port 6380)
✅ Temporal UI (port 8080 - monitoring)

See docs/DOCKER_DEPLOYMENT.md for detailed Docker instructions.

Quick Start with `uv` (Development)

Installation

# Clone the repository
git clone https://github.com/yourusername/code-review.git
cd code-review

# Install dependencies with uv (indexing/chat extras are required to run the server)
uv sync --extra indexing --extra chat

# Set up environment variables
cp .env.example .env
# Edit .env and add your GITHUB_TOKEN

Running the Server

# Option 1: Using uv run (default port 8888)
uv run review-server

# Option 2: Using uv run with custom port
uv run review-server --port 8080

# Option 3: Using the dev script (custom port)
./dev.sh server 8080

# Option 4: Using uvicorn directly
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8080

# Option 5: Activate venv and run
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python -m uvicorn app.main:app --reload --port 8080

# Option 6: Set port via environment variable
PORT=8080 uv run review-server

Running Tests

# Run all tests
uv run pytest

# Run specific test suite
uv run pytest tests/unit
uv run pytest tests/integration

# Run with coverage
uv run pytest --cov=app --cov-report=html

Development Workflow

# Format code
uv run black .

# Lint code
uv run ruff check . --fix

# Type checking (if you add mypy)
uv run mypy app

# Run all quality checks
uv run black . && uv run ruff check . --fix && uv run pytest

Usage

Start the server:
```
uv run review-server
```
Open the Web UI: http://localhost:8000
Start a review:
- Paste the full PR URL (e.g., https://github.com/facebook/react/pull/12345)
- Choose your AI provider (OpenAI or Anthropic) and model
- Optionally provide GitHub token (or set GITHUB_TOKEN env var)
- Click "Start Review"
Chat with your code (NEW!):
- Navigate to /chat in the Web UI
- Select one or more indexed repositories
- Ask questions like:
  - "How does authentication work in this codebase?"
  - "Find security vulnerabilities in the auth module"
  - "Explain how the payment processing flow works"
  - "Compare the error handling between repo-a and repo-b"
- Enable Web Search for external documentation lookup
- Click follow-up suggestions to explore deeper

For detailed AI provider configuration, see docs/AI_PROVIDERS.md.

Advanced Analysis Features

🧠 Semantic Code Indexing

The tool uses tree-sitter for accurate, syntax-aware code parsing:

AST-based chunking: Extracts functions, classes, and methods precisely
Multi-language support: Python, JavaScript, TypeScript, Go, Rust
Stable chunk IDs: Enables caching and tracking across commits
Performance: ~1000 lines/sec parsing speed

🔎 Vector Search & Dependency Graphs

ChromaDB powers semantic code search:

Automatic embeddings: Using sentence-transformers (all-MiniLM-L6-v2)
Semantic similarity: Find similar code patterns across your codebase
Context retrieval: AI reviews leverage relevant examples from your repo
Sub-100ms queries: Fast similarity search even on large codebases

FalkorDB provides symbol-level dependency tracking:

Symbol graph: Functions, classes, and methods as nodes, connected by CALLS, INHERITS_FROM, and TESTED_BY edges (not just file-level imports)
Confidence-tiered edges: Every edge is EXTRACTED (syntactically certain), INFERRED (resolves through a single import hop), or AMBIGUOUS (all candidate targets emitted, for recall)
Blast radius: For each PR, compute the transitive set of impacted symbols, the unchanged files they reach, the tests that exercise them, and a risk score with human-readable "why this is risky" reasons
Critical path detection: Identify most-depended-upon (hub) symbols
GraphRAG-optimized: Super-fast graph queries using GraphBLAS

In reviews (on by default): when blast_radius_enabled is set (the default), each review diffs the changed symbols against the "before" content at the PR's merge-base, computes the blast radius, and injects an Impact Context section into the specialist and single-agent prompts — so the AI knows which callers, files, and tests a change puts at risk. If the graph is unavailable or the comparison base can't be resolved, the review continues without it rather than reporting an incomplete impact as authoritative. Set blast_radius_enabled=false to turn it off.

🗂️ Smart Caching Strategy

Repository-level indexing (one-time, expensive):

Chunk entire codebase at base branch
Generate embeddings for all functions/classes
Build dependency graph (imports, calls)
Store in vector DB + graph DB for reuse across all PRs
Time: ~2-3 minutes for small repos, ~20 minutes for large monorepos

Per-repository caching (not per-owner):

Each repo gets its own index: {owner}-{repo}
Reused across ALL PRs in that repository
Staleness detection (age > 7 days OR commits > 50 behind)
Automatic scheduled rebuilds (daily at 2 AM)

PR-level analysis (fast, incremental):

Only analyze changed files
Query pre-built repo index for context
Typical PR: <10 seconds analysis time
Result: 95% faster reviews after initial indexing

📚 Repository Indexing Management

Web UI at /indexing:

Repository List: View all indexed repositories with status and metadata
Index New Repos: Enter a GitHub URL to index any repository
Statistics Dashboard: View total indexes, files, chunks, cache size
Check Status: Query any repository's index status and freshness
Rebuild Index: Manually trigger full repository re-indexing
Delete Index: Remove indexes for archived repositories
Workflow Controls: Pause, resume, cancel, or terminate indexing in progress
Purge Data: Completely remove all indexed data for a repository
Architecture Diagrams: Generate and view AI-generated Mermaid diagrams

API Endpoints:

POST /api/index/rebuild/{owner}/{repo} - Trigger rebuild
GET /api/index/status/{owner}/{repo} - Get index status
GET /api/index/stats - Cache statistics
DELETE /api/index/{owner}/{repo} - Delete index
GET /api/index/repos - List all indexed repositories

Workflow Control Endpoints:

POST /api/index/workflow/{id}/pause - Pause running workflow
POST /api/index/workflow/{id}/resume - Resume paused workflow
POST /api/index/workflow/{id}/cancel - Cancel with cleanup
POST /api/index/workflow/{id}/terminate - Immediate stop
DELETE /api/index/{owner}/{repo}/purge - Delete ALL data
POST /api/index/{owner}/{repo}/reindex - Force rebuild

Diagram Endpoints:

POST /api/diagrams/generate/{owner}/{repo} - Generate architecture diagram
GET /api/diagrams/{owner}/{repo} - Get cached diagram
GET /api/diagrams/{owner}/{repo}/exists - Check if diagram exists
DELETE /api/diagrams/{owner}/{repo} - Delete diagram
GET /api/diagrams/list - List all diagrams

Temporal Workflows:

ManualIndexRebuildWorkflow - User-triggered via UI (supports pause/resume signals)
ScheduledIndexRebuildWorkflow - Cron-based (daily at 2 AM)
IncrementalIndexUpdateWorkflow - Webhook-triggered (future)
ArchitectureDiagramWorkflow - AI-powered Mermaid diagram generation

🔄 Index Lifecycle

First PR in Repository:
├─ Trigger: User submits PR
├─ Check: Index exists? → No
├─ Action: Build index (clone, chunk, embed, graph)
├─ Time: ~2-3 minutes
└─ Result: Cached for future PRs

Subsequent PRs (cached):
├─ Trigger: User submits PR
├─ Check: Index exists? → Yes
├─ Check: Is stale? → No
├─ Action: Use cached index
├─ Time: <1 second
└─ Result: Instant context retrieval

Stale Index (scheduled):
├─ Trigger: Cron (daily 2 AM)
├─ Check: Age > 7 days OR commits > 50?
├─ Action: Rebuild in background
└─ Result: Fresh index ready

📊 How It Works

PR Submitted
    ↓
1. Fetch changed files (GitHub API)
    ↓
2. Check if repo is indexed
    ├─→ No: Index base branch (one-time)
    └─→ Yes: Use cached index
    ↓
3. Chunk changed files (tree-sitter)
    ↓
4. Search similar code (vector DB)
    ↓
5. AI reviews with context
    ↓
6. Stream results to UI

🎯 Benefits

Better Reviews: AI has context from similar code in your repo
Faster After First: 95% faster after initial repository indexing
Lower Costs: Fewer API calls by reusing cached context
Scalable: Works with codebases from 1K to 1M+ lines of code

Supported PR URL Formats

GitHub: https://github.com/owner/repo/pull/123
GitLab: https://gitlab.com/owner/repo/-/merge_requests/123
Bitbucket: https://bitbucket.org/owner/repo/pull-requests/123
Azure DevOps: https://dev.azure.com/org/project/_git/repo/pullrequest/123

Note: Currently only GitHub is fully supported. Other providers coming soon!

Architecture

The system is built around three loosely-coupled subsystems sharing a single index.

graph TD
    UI["Frontend (React + Vite)"]
    API["FastAPI<br/>routers: review · index · diagrams · chat · config"]
    Worker["Temporal Worker"]
    Temporal[(Temporal Server)]
    Chroma[(ChromaDB<br/>embeddings)]
    Falkor[(FalkorDB<br/>dependency graph)]
    Specs["Specialist Agents<br/>security · bug-finder · refactoring ·<br/>architecture · explainer · comparison · web-search"]

    UI -->|HTTP + SSE| API
    API -->|start workflow| Temporal
    API -->|query / signal| Temporal
    Temporal --> Worker
    Worker -->|review activities| Specs
    Worker -->|chunk + embed| Chroma
    Worker -->|dep edges| Falkor
    API -->|RAG retrieval| Chroma
    API -->|impact analysis| Falkor
    API -->|chat orchestration| Specs

Subsystem 1 — Durable Review Pipeline. ReviewWorkflow (Temporal) orchestrates PR fetch → file analysis → summary → optional GitHub posting, with pause/resume signals and a get_progress query that drives the UI's phase indicator. Activities are referenced by string name to keep heavy deps (e.g., pydantic-ai) out of the workflow sandbox. See app/workflows/review_workflow.py and app/services/review/coordinator.py.

Subsystem 2 — Indexing & Retrieval. Tree-sitter parses Python/JS/TS/Go/Rust into function/class chunks; sentence-transformers embeds them into ChromaDB. A separate FalkorDB graph stores a symbol-level dependency graph (calls, inheritance, test coverage) for blast-radius impact scoring. Indexing has its own family of workflows (ManualIndexRebuild, IncrementalIndexUpdate, ScheduledIndexRebuild) with first-class pause/resume/cancel/purge. See docs/INDEXING.md.

Subsystem 3 — Multi-Agent Surface. Seven specialists inherit BaseSpecialist (app/services/specialists/base.py), each with a Pydantic output_type. The same agents serve two consumers: MultiAgentAnalyzer (parallel review of PR files, then dedup/rank via Synthesizer) and ChatOrchestrator (interactive delegation across one or more indexed repos).

code-review/
├── app/
│   ├── core/           # Configuration, models, prompts
│   ├── services/       # Git adapters, analyzer, vector store, code chunker
│   │   ├── github_adapter.py       # GitHub API integration
│   │   ├── analyzer.py             # AI-powered code analysis
│   │   ├── vector_store.py         # Vector DB abstraction
│   │   ├── chromadb_store.py       # ChromaDB implementation
│   │   ├── code_chunker.py         # Semantic code chunking + symbol/change extraction
│   │   ├── dependency_analyzer.py  # FalkorDB symbol graph + blast-radius computation
│   │   ├── python_call_resolver.py # Confidence-tiered CALLS edge resolution
│   │   ├── blast_radius_types.py   # Symbol / edge / BlastRadius data model
│   │   └── impact_analyzer.py      # File-level dependency graph & risk scoring
│   ├── workflows/      # Temporal workflows & activities
│   ├── static/         # Web UI (HTML + JavaScript)
│   └── main.py         # FastAPI application
├── tests/
│   ├── unit/           # Unit tests (600+ tests)
│   └── integration/    # Integration tests
├── rules/
│   └── global/         # Language-specific best practices (Python, TS, Rust, Go, NestJS, React)
├── docs/               # Documentation
├── pyproject.toml      # Project configuration (uv-based)
└── docker-compose.yml  # Docker setup (6 services)

Configuration

AI Provider Configuration

Web UI at /config:

Select your preferred AI provider (OpenAI, Anthropic, Google, Mistral, etc.)
Configure API keys with secure storage (stored in .ai-review/secrets.json)
Adjust model settings: temperature, review strictness, focus areas
Test API key validity before saving

Supported Providers:

Provider	Models	API Key Required
OpenAI	GPT-4o, GPT-4o-mini, GPT-4-turbo, o1, o3-mini	✅ `OPENAI_API_KEY`
Anthropic	Claude 3.5 Sonnet, Claude 3 Opus/Haiku	✅ `ANTHROPIC_API_KEY`
Google	Gemini 1.5 Pro/Flash, Gemini 2.0	✅ `GOOGLE_API_KEY`
Mistral	Mistral Large, Codestral, Mixtral	✅ `MISTRAL_API_KEY`
Groq	Llama 3.1, Mixtral (fast inference)	✅ `GROQ_API_KEY`
Ollama	Any local model	❌ (local)

API Key Priority:

Environment variable (e.g., OPENAI_API_KEY)
Stored key in .ai-review/secrets.json
Falls back to test model if none configured

Repository Review Configuration

Create .ai-review/review.yaml in your repository:

version: "1.0"
modes:
  default: "standard"
  definitions:
    standard:
      strictness: "normal"
      focus: ["correctness", "security", "maintainability"]
    security_audit:
      strictness: "high"
      focus: ["security"]

files:
  - pattern: "src/auth/**"
    mode: "security_audit"
  - pattern: "**/*.test.ts"
    rules:
      "no-assertions": { severity: "error" }

API Endpoints

GET / - Web UI
GET /health - Health check

POST /api/review - Start a code review

{
  "pr_url": "https://github.com/owner/repo/pull/123",
  "github_token": "ghp_xxx" // optional
}

GET /api/pr/{owner}/{repo}/{pr_number} - Get PR metadata
GET /api/pr/{owner}/{repo}/{pr_number}/files - Get changed files

Chat API Endpoints

POST /api/chat/query - Send a chat query (non-streaming)

POST /api/chat/query/stream - Stream chat response (SSE)

{
  "message": "How does authentication work?",
  "selected_repositories": ["owner/repo1", "owner/repo2"],
  "conversation_history": [],
  "enable_web_search": false
}

GET /api/workspaces - List all workspaces
POST /api/workspaces - Create a new workspace
DELETE /api/workspaces/{id} - Delete a workspace

Environment Variables

# Required
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Server Configuration
HOST=0.0.0.0          # Default: 0.0.0.0
PORT=8000             # Default: 8000

# Optional
OPENAI_API_KEY=sk-xxxxxxxxxxxx  # For production AI models
GITLAB_TOKEN=glpat-xxxxxxxxxxxx
DEBUG=false

Docker Deployment

# Start all services
docker compose up

# Access the UI
open http://localhost:8000

# Access Temporal UI
open http://localhost:8080

Development

Adding a New Git Provider

Create adapter in app/services/
Implement GitHostAdapter interface
Add tests in tests/unit/

Adding New Analysis Rules

Create Markdown file in rules/
Update review.yaml to reference it
Prompts automatically include relevant rules

Contributing

See CONTRIBUTING.md for the micro-commit strategy and development workflow.

Testing with `uv`

# Install test dependencies
uv sync --group dev

# Run quick test
uv run pytest tests/unit/test_dummy.py

# Run with verbose output
uv run pytest -v

# Run specific test
uv run pytest tests/unit/test_api.py::test_health_endpoint

# Watch mode (requires pytest-watch)
uv run ptw

Troubleshooting

`uv` not found

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

Import errors

# Reinstall dependencies (include the runtime extras)
uv sync --reinstall --extra indexing --extra chat

Port already in use

# Option 1: Use environment variable
PORT=8080 uv run review-server

# Option 2: Use command-line argument
uv run review-server --port 8080

# Option 3: Use dev script
./dev.sh server 8080

# Option 4: Use uvicorn directly
uv run uvicorn app.main:app --port 8080

License

This project is source-available under the Functional Source License, Version 1.1, MIT Future License (FSL-1.1-MIT). See LICENSE for the full text.

In short: you may use, modify, and redistribute the software for any purpose except a Competing Use (offering it as a commercial product or service that substitutes for, or is substantially similar to, this software). Internal use, non-commercial education, non-commercial research, and professional services for licensees are expressly permitted. Two years after each version is released, it additionally becomes available to you under the MIT license.

Credits

Built with:

FastAPI - Web framework
Pydantic AI - AI agent framework
Temporal - Workflow orchestration
ChromaDB - Vector database for semantic search
tree-sitter - Incremental parsing for code analysis
sentence-transformers - State-of-the-art text embeddings
uv - Fast Python package manager

Name		Name	Last commit message	Last commit date
Latest commit History 460 Commits
.github		.github
app		app
docs		docs
ee		ee
frontend		frontend
rules/global		rules/global
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
AGENTS.md		AGENTS.md
DCO		DCO
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
dev.sh		dev.sh
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
start-docker.sh		start-docker.sh
uv.lock		uv.lock
verify_graph.py		verify_graph.py

Folders and files

Latest commit

History

Repository files navigation

AI Code Review Assistant

Features

Core Capabilities

🚀 Advanced Analysis (World-Class Features)

🎮 Workflow Control Features

📊 Architecture Diagrams

💬 Multi-Repository Chat (NEW!)

🧠 Multi-Agent Architecture

🔍 Multi-Agent PR Review (NEW!)

Quick Start with Docker (Recommended) 🐳

Quick Start with uv (Development)

Installation

Running the Server

Running Tests

Development Workflow

Usage

Advanced Analysis Features

🧠 Semantic Code Indexing

🔎 Vector Search & Dependency Graphs

🗂️ Smart Caching Strategy

📚 Repository Indexing Management

🔄 Index Lifecycle

📊 How It Works

🎯 Benefits

Supported PR URL Formats

Architecture

Configuration

AI Provider Configuration

Repository Review Configuration

API Endpoints

Chat API Endpoints

Environment Variables

Docker Deployment

Development

Adding a New Git Provider

Adding New Analysis Rules

Contributing

Testing with uv

Troubleshooting

uv not found

Import errors

Port already in use

License

Credits

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Quick Start with `uv` (Development)

Testing with `uv`

`uv` not found