GitHub - KacemMathlouthi/metis: AI platform for GitHub pull requests with a cloud coding agent for autonomous code review, background issue resolution, and automatic PR title/summary generation.

AI-Powered GitHub Code Review Platform

Overview

Metis is an AI-powered GitHub code reviewer built as a GitHub App. It listens to pull request webhooks, analyzes changes in isolated sandboxes, and posts actionable findings directly on PRs.

Production-grade monorepo:

Backend: Python, FastAPI, Celery, PostgreSQL, Redis, AI Agents
Frontend: React 19, TypeScript, Vite (Rolldown), Tailwind v4, Neo-brutalist UI
Agent Runtime: Daytona sandbox + tool-augmented LLM agents
Multi-LLM Support: LiteLLM (Vertex AI, OpenAI, Anthropic, Mistral)

Key Capabilities

AI-Powered Code Review

Autonomous agents analyze PRs in isolated sandboxes
Progressive inline findings posted directly on diff lines
Multi-provider LLM support - switch providers with one env var
Configurable sensitivity - from INFO to CRITICAL findings
Category tagging - SECURITY, PERFORMANCE, BUG, STYLE, etc.

Issue-to-PR Workflow

Launch autonomous coding agents from GitHub issues
Agents write code, run tests, commit, and create PRs
Track progress in real-time with metrics and timelines
Full conversation and tool trace persistence

Repository Management

Multi-repository support - one GitHub App, many repos
Per-repository configuration - custom instructions, ignore patterns
GitHub OAuth integration - secure user authentication

Analytics Dashboard

Review metrics and trends
AI-detected issues table with filters
Agent run history and performance metrics
Real-time progress monitoring

Architecture

High-Level System Design

┌─────────────┐
│   GitHub    │
│   Webhooks  │
└──────┬──────┘
       │ Pull Request Event
       ▼
┌───────────────────────────────────┐
│       FastAPI Backend             │
│  ┌─────────────────────────────┐  │
│  │   Webhook Handler           │  │
│  │   - Verify signature        │  │
│  │   - Create Review (PENDING) │  │
│  │   - Queue Celery tasks      │  │
│  │   - Return 202 Accepted     │  │
│  └─────────────┬───────────────┘  │
│                │                  │
└────────────────┼──────────────────┘
                 │
                 ▼
         ┌───────────────┐
         │  Redis Queue  │
         └───────┬───────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│       Celery Worker                 │
│  ┌───────────────────────────────┐  │
│  │   AI Agent System             │  │
│  │                               │  │
│  │  1. Create Daytona Sandbox    │  │
│  │  2. Clone PR Branch           │  │
│  │  3. Run Agent Loop:           │  │
│  │     - Plan (LLM)              │  │
│  │     - Execute Tools           │  │
│  │     - Post Findings           │  │
│  │     - Evaluate                │  │
│  │  4. Post Final Review         │  │
│  │  5. Cleanup Sandbox           │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Core Request Flow

GitHub sends webhook for PR changes (opened, synchronize, reopened)
Backend validates signature and records pending review
Celery queues agent tasks for review and summary generation
Agent executes in sandbox with controlled tool access:
- Reads files and analyzes code
- Runs tests and linters
- Posts inline findings progressively
- Generates final review summary
Findings posted to GitHub as review comments and persisted to database
Frontend dashboards expose progress, analytics, and repository controls

Agent Tools

Tools Available (23 total):

File Operations (6): read, list, search, replace, create, delete
Git Operations (8): status, branches, create_branch, checkout, add, commit, push, pull
Process Execution (4): command, code, tests, linter
Review Posting (2): post_inline_finding, post_file_finding
Completion (3): finish_review, finish_task, finish_summary

Multi-LLM Support

Switch AI providers with a single environment variable:

# Vertex AI (Google)
MODEL_NAME=vertex_ai/gemini-3-flash-preview

# OpenAI
MODEL_NAME=gpt-4o

# Anthropic
MODEL_NAME=claude-3-5-sonnet-20241022

# Mistral
MODEL_NAME=mistral/mistral-large-latest

No code changes required. LiteLLM handles provider differences.

Repository Structure

metis/
├── backend/                    # FastAPI backend (Python)
│   ├── app/
│   │   ├── api/                # API route handlers
│   │   ├── core/               # Configuration & infrastructure
│   │   ├── db/                 # Database layer
│   │   ├── models/             # SQLAlchemy ORM models
│   │   ├── repositories/       # Repository pattern (data access)
│   │   ├── services/           # Business logic
│   │   ├── agents/             # AI Agent System
│   │   │   ├── base.py         # BaseAgent
│   │   │   ├── loop.py         # AgentLoop orchestrator
│   │   │   ├── implementation/ # ReviewAgent, BackgroundAgent, SummaryAgent
│   │   │   ├── prompts/        # System prompts
│   │   │   ├── sandbox/        # Daytona integration
│   │   │   └── tools/          # 23 tools
│   │   ├── schemas/            # Pydantic models
│   │   ├── tasks/              # Celery background tasks
│   │   └── utils/              # Utilities
│   ├── alembic/                # Database migrations
│   ├── tests/                  # Test suite
│   └── README.md               # Backend documentation
│
├── frontend/                   # React frontend (TypeScript)
│   ├── src/
│   │   ├── components/         # React components
│   │   │   ├── ui/             # shadcn/ui components
│   │   │   ├── dashboard/      # Dashboard components
│   │   │   ├── landing/        # Landing page sections
│   │   │   └── issues/         # Issue & agent components
│   │   ├── contexts/           # React Context providers
│   │   ├── pages/              # Route pages
│   │   ├── lib/                # Utilities (API client, icons)
│   │   └── types/              # TypeScript definitions
│   └── README.md               # Frontend documentation
│
├── static/                     # Static assets
│   └── metis-logo.svg
│
├── docker-compose.dev.yml      # Development infrastructure
├── CONTRIBUTING.md             # Contribution guidelines
├── CODE_OF_CONDUCT.md          # Code of conduct
├── SECURITY.md                 # Security policy
└── README.md                   # This file

Quick Start

Prerequisites

Python 3.10+
Node.js 20+ with pnpm
Docker & Docker Compose
GitHub App credentials
Daytona Account (https://app.daytona.io)
UV package manager

1. Start Infrastructure

# Start PostgreSQL, Redis, pgAdmin, Redis Insight
docker-compose -f docker-compose.dev.yml up -d

Services:

PostgreSQL: localhost:5432
Redis: localhost:6379
pgAdmin: http://localhost:5050 ([email protected] / admin)

2. Setup Backend

cd backend

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Run migrations
alembic upgrade head

# Start backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

3) Run worker

# Start Celery worker
cd backend
celery -A app.core.celery_app worker --loglevel=info

Optional - Celery monitoring:

# Start Flower
celery -A app.core.celery_app flower --port=5555
# Visit http://localhost:5555

Backend available at: http://localhost:8000

4. Setup Frontend

cd frontend

# Install dependencies
pnpm install

# Start dev server
pnpm dev

Frontend available at: http://localhost:5173

5. Configure GitHub App

Quick summary:

Create GitHub App with required permissions
Generate and download private key (.pem file)
Set webhook URL to http://your-domain/webhooks/github
Add credentials to backend .env

6. Access the Application

Visit frontend: http://localhost:5173
Click "Login with GitHub" - redirects to GitHub OAuth
Authorize the app - redirected back to dashboard
Sync repositories - on Repositories page, click "Sync from GitHub"
Enable reviews - toggle repositories you want Metis to review
Open a PR on an enabled repository - Metis automatically reviews it!

Documentation

Core Documentation

Backend README - Complete backend architecture, API reference, agent system
Frontend README - React app structure, components, state management

Development

Development Workflow

Backend:

cd backend

# Code quality
ruff check .              # Lint
ruff format .             # Format
mypy app/                 # Type check
pytest                    # Run tests

# Database
alembic revision --autogenerate -m "description"
alembic upgrade head

# Pre-commit hooks
pre-commit install
pre-commit run --all-files

Frontend:

cd frontend

# Code quality
pnpm lint                 # ESLint
pnpm format               # Prettier
pnpm build                # Type check + build

# Development
pnpm dev                  # Dev server with HMR

Development Stack

Backend:

FastAPI for async API endpoints
Celery for background task processing
SQLAlchemy 2.0 for async ORM
Alembic for database migrations
Redis for task queue and caching
LiteLLM for multi-provider LLM access
Daytona for isolated code execution

Frontend:

React 19 with React Compiler
TypeScript for type safety
Vite (Rolldown) for fast builds
Tailwind CSS v4 for styling
shadcn/ui for component library
React Router v7 for routing

Continuous Integration

GitHub Actions workflows:

Backend: Ruff, MyPy, Pytest (on push)
Frontend: ESLint, TypeScript, build (on push)
CodeQL: Security scanning

Environment Variables

Backend (.env):

# Database
DATABASE_URL=postgresql+asyncpg://...

# GitHub
GITHUB_APP_ID=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_WEBHOOK_SECRET=...
GITHUB_SECRET_KEY_PATH=./app.private-key.pem

# LLM Provider
MODEL_NAME=vertex_ai/gemini-3-flash-preview
VERTEX_PROJECT=...
VERTEX_LOCATION=global

# Daytona
DAYTONA_API_KEY=...
DAYTONA_TARGET=eu

Frontend (.env.production):

VITE_API_URL=https://api.metis.example.com

Security

Webhook signature verification is enforced for GitHub events.
OAuth tokens are encrypted at rest.
Session auth uses HTTP-only cookies and refresh flow.

If you discover a vulnerability, open a private security report or contact the maintainer directly until SECURITY.md is finalized.

Contributing

We welcome contributions! Please read our contributing guidelines first.

How to Contribute

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes following our code standards
Run quality checks:
- Backend: ruff check . && mypy app/ && pytest
- Frontend: pnpm lint && pnpm format:check && pnpm build
Commit your changes: git commit -m 'feat: add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

License

This project is licensed under the MIT License - see LICENSE file for details.

Star History

If you find Metis useful, please consider starring the repository!

Made with ❤️ for better code reviews

Name		Name	Last commit message	Last commit date
Latest commit History 331 Commits
.claude		.claude
.github/workflows		.github/workflows
backend		backend
daytona @ 847f154		daytona @ 847f154
frontend		frontend
static		static
.gitignore		.gitignore
.gitmodules		.gitmodules
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.dev.yml		docker-compose.dev.yml

Folders and files

Latest commit

History

Repository files navigation

Overview

Key Capabilities

AI-Powered Code Review

Issue-to-PR Workflow

Repository Management

Analytics Dashboard

Table of Contents

Architecture

High-Level System Design

Core Request Flow

Agent Tools

Multi-LLM Support

Repository Structure

Quick Start

Prerequisites

1. Start Infrastructure

2. Setup Backend

3) Run worker

4. Setup Frontend

5. Configure GitHub App

6. Access the Application

Documentation

Core Documentation

Development

Development Workflow

Development Stack

Continuous Integration

Environment Variables

Security

Contributing

How to Contribute

License

Star History

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages