Skip to content

ni5h4nt/code-review

BranchesTags

Repository files navigation

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
  • 📊 Impact Analysis - Dependency graph & risk scoring for changed code
  • 🎯 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 8000)
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

  1. Start the server:

    uv run review-server

  2. Open the Web UI: http://localhost:8000

  3. 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"

  4. 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 dependency tracking:

  • File-level dependencies: Track imports and relationships
  • Impact radius analysis: Multi-hop graph traversal to find affected code
  • Critical path detection: Identify most-depended-upon files
  • GraphRAG-optimized: Super-fast graph queries using GraphBLAS

🗂️ 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
Loading

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 docs/AGENT_ARCHITECTURE.md.

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 import/dependency edges for 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
│   │   └── impact_analyzer.py      # Dependency graph & risk scoring
│   ├── workflows/      # Temporal workflows & activities
│   ├── static/         # Web UI (HTML + JavaScript)
│   └── main.py         # FastAPI application
├── tests/
│   ├── unit/           # Unit tests (43 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:

  1. Environment variable (e.g., OPENAI_API_KEY)
  2. Stored key in .ai-review/secrets.json
  3. 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

  1. Create adapter in app/services/
  2. Implement GitHostAdapter interface
  3. Add tests in tests/unit/

Adding New Analysis Rules

  1. Create Markdown file in rules/
  2. Update review.yaml to reference it
  3. 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

MIT

Credits

Built with:

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages