Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
The AI Code Reviewer is a GitHub App designed to automate the pull request review process using Large Language Models (LLMs) and Retrieval-Augmented Generation (RAG). By integrating directly with GitHub webhooks, the system fetches code diffs, analyzes them against the existing codebase and past review history, and posts actionable, structured feedback as inline comments on the PR.
Sources: README.md:3-6, CLAUDE.md:7-10
The project is structured as a monorepo consisting of two primary processes: a Next.js web application for user onboarding and webhook intake, and a Node.js background worker for executing heavy LLM and indexing tasks. These processes communicate through a shared PostgreSQL database using pg-boss as a job queue.
Sources: README.md:126-140
Prerequisites
Before starting the local setup, ensure the following tools and accounts are available:
- Node.js: Version 20 or higher.
- Docker: Required to run the PostgreSQL database.
- GitHub App: A custom GitHub App created in your GitHub settings.
- ngrok: Used to expose the local webhook endpoint (
/api/webhooks/github) to GitHub. - OpenAI API Key: Required for generating AI reviews.
Sources: README.md:329-335
Local Development Workflow
The development environment relies on three concurrent terminal processes to handle the full lifecycle of a PR review.
1. Environment Configuration
Copy the .env.example file to .env.local and populate it with the required credentials. Key variables include:
| Variable | Description |
|---|---|
GITHUB_APP_ID | Numeric ID from GitHub App settings. |
GITHUB_APP_PRIVATE_KEY | PEM private key for authentication. |
GITHUB_WEBHOOK_SECRET | Secret for HMAC signature verification. |
OPENAI_API_KEY | Key for LLM review calls. |
ENCRYPTION_KEY | 64 hex chars for encrypting secrets at rest. |
Sources: README.md:347-362, README.md:405-416
2. Infrastructure Setup
The project uses Docker for the database and Prisma for schema management.
# Start PostgreSQL
docker compose -f docker-compose.dev.yml up -d
# Run DB migrations
npx prisma migrate deploy --schema packages/db/prisma/schema.prisma
Sources: README.md:341-345
3. Running the Application
The monorepo uses npm workspaces. Start the web server and the worker in separate terminals.
# Terminal 1: Web server (Port 3000)
npm run dev -w web
# Terminal 2: Background worker
npm run dev -w worker
# Terminal 3: Webhook proxy
ngrok http 3000
Sources: README.md:374-383, apps/web/package.json:8
System Architecture
The following diagram illustrates the interaction between the local development components and external GitHub services:
The web server handles fast HTTP interactions and stores webhook payloads, while the worker manages slow, resource-intensive tasks like LLM calls.
Sources: README.md:131-140, CLAUDE.md:16-24
Onboarding and Repository Activation
By default, the app adopts an opt-in model. No repositories are reviewed until explicitly enabled by a user through the dashboard.
- Sign In: Authenticate via GitHub OAuth at
localhost:3000. - Installation Selection: The onboarding page lists all GitHub installations (Personal or Organization) where the app is installed.
- Enable Repo: Clicking "Enable" on a repository triggers the indexing process.
Sources: README.md:394-399, apps/web/app/onboarding/page.tsx:185-212
Initial Indexing (Layer 1 RAG)
When a repository is enabled, an IndexRepository job is enqueued. The system clones the repository structure and chunks code files using Tree-sitter AST parsing.
Critical Setup Configurations
- GitHub App Permissions: Ensure the app has "Read & Write" access to Pull Requests and is subscribed to
pull_request,installation, andinstallation_repositoriesevents. - Webhook URL: In GitHub App settings, set the Webhook URL to your ngrok address (e.g.,
https://<id>.ngrok.io/api/webhooks/github). - Prisma Studio: Use
npx prisma studioto manually inspect theAiReviewandRepositorytables for debugging.
Sources: README.md:385-391, README.md:396
Summary
Setting up the AI Code Reviewer requires a hybrid of local infrastructure (Postgres/Node) and external integrations (GitHub/OpenAI). The split architecture between apps/web and apps/worker ensures that the system remains responsive to GitHub's webhook requirements while processing complex AI reviews asynchronously. Once the environment is configured and a repository is enabled, the system automatically transitions into an active state, ready to process incoming pull requests.