AI-powered GitHub Pull Request review system with a web dashboard and an evidence-grounded Ask Quorum chatbot.
Quorum reviews Pull Requests with specialized AI agents (static-analysis evidence, generated tests run in a Docker sandbox, measured coverage), produces a deterministic 0–100 Merge Readiness Score, and stores results in PostgreSQL.
Measure, don't merely claim. Quorum must not claim a test passed unless it actually passed, that coverage improved unless it was measured, or that a security issue exists without supporting evidence.
- Receives GitHub Pull Request events through webhooks.
- Analyzes the changed code (diff, Python AST, Semgrep evidence).
- Generates and executes tests inside an isolated Docker sandbox.
- Measures coverage before/after and computes a deterministic Merge Readiness Score.
- Stores results in PostgreSQL and posts a review summary back to GitHub.
- Provides a React web dashboard and an evidence-grounded Ask Quorum chatbot.
- GitHub Pull Request integration (webhooks + REST API)
- AI-assisted code/security analysis
- Generated tests with real execution and verification
- Coverage measurement and delta
- Deterministic Merge Readiness Score
- Quorum Web Dashboard
- Ask Quorum — grounded in a selected review's evidence
Features beyond the currently implemented phases are planned by
roadmap.md. Until the analysis pipeline exists, the dashboard's analysis views show honest "not yet available" states rather than fake data.
- Open the Quorum Web Dashboard.
- Sign in with GitHub (GitHub OAuth authenticates the user).
- Install/authorize the Quorum GitHub App.
- Select the repositories Quorum is allowed to access.
- Quorum receives Pull Request events automatically from GitHub.
- Quorum runs its existing analysis pipeline on the Pull Request.
- The user sees security findings, generated-test results, coverage, and the Merge Readiness result in the dashboard and as GitHub PR feedback.
- The user can ask questions about the review through Ask Quorum.
Users do not need to install Quorum or its analysis components locally. The Quorum backend runs the analysis infrastructure. Local installation is only relevant to Quorum development/self-hosted development environments.
GitHub
│ (webhooks / REST API)
▼
FastAPI
│
▼
Quorum Analysis Pipeline
│
▼
PostgreSQL
│
▼
FastAPI REST API
│
▼
React Web Dashboard
The frontend communicates only with the FastAPI REST API. It never accesses PostgreSQL, Docker, Ollama, Semgrep, or GitHub server secrets directly.
| Layer | Technology |
|---|---|
| Backend | Python 3.13, FastAPI, Uvicorn |
| Data | PostgreSQL, SQLAlchemy, Alembic |
| GitHub | GitHub App, webhooks, REST API (httpx, PyJWT) |
| Frontend | React, TypeScript, Vite, Tailwind CSS, shadcn/ui |
| Analysis (planned) | Semgrep, Ollama (Qwen2.5-Coder), Docker sandbox |
| Tests | pytest, pytest-cov |
Quorum/
├── src/quorum/
│ ├── main.py # FastAPI app, /health, /webhooks/github
│ ├── config.py # settings loaded from .env
│ ├── api/ # dashboard REST API (/api/...)
│ ├── auth/ # GitHub OAuth login + sessions
│ ├── database/ # SQLAlchemy models, engine, repository helpers
│ └── github/ # GitHub API client, App JWT, webhook signing
├── frontend/ # React + Vite + TypeScript dashboard
├── tests/ # backend tests (pytest)
├── alembic/ # database migrations
├── roadmap.md # phased build plan (source of truth)
├── AGENTS.md # rules/workflow for AI coding agents
├── requirements.txt
└── .env.example
git clone <repository-url>
cd QuorumThe project targets Python 3.13.x. Windows (PowerShell):
python -m venv .venv
.\.venv\Scripts\Activate.ps1pip install -r requirements.txtCopy the template and fill in real values (never commit .env):
Copy-Item .env.example .envConfigure at least:
GITHUB_WEBHOOK_SECRET— secret shared with the GitHub App webhook.GITHUB_APP_ID,GITHUB_APP_PRIVATE_KEY_PATH— the GitHub App id and the filesystem path to its generated private key (.pem). Keep the key out of Git (.gitignorecovers*.pemandsecrets/).GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,GITHUB_APP_SLUG— used by the GitHub login flow.GITHUB_REDIRECT_URI— OAuth callback (defaulthttp://localhost:8000/auth/callback).FRONTEND_URL— frontend origin the OAuth callback redirects to after login (defaulthttp://localhost:5173).DATABASE_URL— PostgreSQL connection string, e.g.postgresql+psycopg://USER:PASSWORD@localhost:5432/quorum.
- Start PostgreSQL locally (default port
5432). - Create the database named in
DATABASE_URL(the example usesquorum). - Apply migrations:
alembic upgrade headFrom the repository root:
uvicorn --app-dir src quorum.main:app --reloadcd frontend
npm install
npm run dev- Backend root: http://localhost:8000/
- Health: http://localhost:8000/health →
{"status":"ok"} - Frontend: http://localhost:5173/
- Sign in: http://localhost:5173/login (or the header "Sign in")
Backend:
pytestFrontend (typecheck + production build; there are no frontend unit tests yet):
cd frontend
npm run buildTo test real GitHub webhook delivery, expose the local backend with a tunnel such as Cloudflare Tunnel and point the GitHub App webhook at it. Signature verification is already implemented and tested; a tunnel is not required for local-only development.
- Phase 0–4: implemented and verified — FastAPI skeleton, GitHub App + OAuth, GitHub API service layer, and PostgreSQL (models, migration, webhook persistence). (Phase 0 setup items such as Docker, Ollama, and CI are still pending.)
- Phase 16 Dashboard: in progress — foundation through Settings are implemented (Chunks 0–8) on the
feature/web-dashboardbranch. - Phase 5–14: remaining backend analysis pipeline (orchestrator, diff/AST, Semgrep, LLM layer, agents, Docker sandbox, synthesis, GitHub comment).
- Ask Quorum: pending — requires the analysis/chat backend.
roadmap.md— the phased 70-day build plan and detailed specification (source of truth for what to build and in what order).AGENTS.md— development rules and the chunk-by-chunk workflow for AI coding agents.