MAGI Review

🏛️ AI Code Review Bot inspired by Evangelion's MAGI System

Three personas (MELCHIOR, BALTHASAR, CASPER) evaluate PRs from different perspectives. Approves when 2/3 or more personas agree.

🎭 Personas

Persona	Role	Focus	Personality
🔬 MELCHIOR	Scientist	Code efficiency, algorithms, bugs, security	Cold and technical
👩‍👧 BALTHASAR	Mother	Maintainability, readability, conventions, tests	Strict but collaborative
💃 CASPER	Woman/Human	UX/UI consistency, user experience	Intuitive and emotional

🚀 Quick Start

Choose from 3 LLM Providers:

Provider	Default Model	Environment Variable
Gemini	`gemini-2.5-flash`	`GEMINI_API_KEY` or `GCP_PROJECT_ID`
OpenAI	`gpt-5.2`	`OPENAI_API_KEY`
Claude	`claude-sonnet-4-5-20250929`	`ANTHROPIC_API_KEY`

Option 1: Gemini (Default)

- uses: WillowRyu/project-judge@main
  with:
    gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Option 2: OpenAI (GPT-5)

- uses: WillowRyu/project-judge@main
  with:
    openai_api_key: ${{ secrets.OPENAI_API_KEY }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/magi.yml:

provider:
  type: openai
  model: gpt-5.2 # optional

Option 3: Claude (Anthropic)

- uses: WillowRyu/project-judge@main
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/magi.yml:

provider:
  type: claude
  model: claude-sonnet-4-5-20250929 # optional

Option 4: GCP Vertex AI (Enterprise)

- uses: google-github-actions/auth@v2
  with:
    credentials_json: ${{ secrets.GCP_SA_KEY }}

- uses: WillowRyu/project-judge@main
  with:
    gcp_project_id: ${{ secrets.GCP_PROJECT_ID }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Full Workflow Example

.github/workflows/magi-review.yml:

name: MAGI Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  magi-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: WillowRyu/project-judge@main
        with:
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Comment-Triggered Re-Review

Run review only on PR open, and re-run via /magi-review comment:

.github/workflows/magi-review.yml:

name: MAGI Review

on:
  pull_request:
    types: [opened] # Only on first open
  issue_comment:
    types: [created] # Re-trigger via comment

permissions:
  contents: read
  pull-requests: write

jobs:
  magi-review:
    runs-on: ubuntu-latest
    if: |
      github.event_name == 'pull_request' ||
      (github.event_name == 'issue_comment' && 
       github.event.issue.pull_request &&
       contains(github.event.comment.body, '/magi-review'))

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event_name == 'issue_comment' && format('refs/pull/{0}/head', github.event.issue.number) || '' }}

      - uses: WillowRyu/project-judge@main
        with:
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Usage:

Trigger	When
PR Created	Auto-run once
Code Push	❌ No run
`/magi-review` comment	✅ Re-run

⚙️ Configuration

Customize behavior with .github/magi.yml:

version: 1

# Provider settings (gemini | openai | claude)
provider:
  type: gemini
  model: gemini-2.5-flash # optional

# Voting settings
voting:
  required_approvals: 2 # Required approval count

# Optimization & safety guard
optimization:
  prompt_compression: true
  context_caching: true
  hard_cut:
    enabled: true
    max_changed_files: 300
    max_changed_lines: 100000

# Debate feature
debate:
  enabled: true
  max_rounds: 1
  trigger: disagreement # conflict | disagreement | always

# Output settings
output:
  pr_comment:
    enabled: true
    style: detailed # summary | detailed
  labels:
    enabled: true
    approved: magi-approved
    rejected: magi-changes-requested

# Notifications
notifications:
  slack:
    enabled: true
    notify_on: all # all | rejection | approval

# Ignore files
ignore:
  files:
    - "*.lock"
    - ".generated."
  paths:
    - "node_modules/"
    - "dist/"

Generated files are ignored by default (for example: generated/, __generated__/, .generated., .pb., .g.dart, .graphql.dart, .designer.cs).

Note: A rejected result does not fail the workflow check by itself. Gate merges using the result output (approved / rejected / skipped / error) or the applied label (e.g., branch protection on the magi-changes-requested label).

Failed reviews abstain. If a persona's model call fails, that vote is excluded from the tally — it never counts as an approval. If fewer valid reviews remain than required_approvals (quorum not reached), result is error and the action fails; just re-run it (usually a transient provider or rate-limit error).

📱 Slack Notifications

Send review results to Slack channel.

Setup

Create Slack Webhook:
- Go to Slack → Apps → "Incoming Webhooks"
- Select channel and create webhook URL
Add to GitHub Secrets:
- Add SLACK_WEBHOOK_URL to repository secrets
Update Workflow:

- uses: WillowRyu/project-judge@main
  with:
    gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
    slack_webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}

Enable in magi.yml:

notifications:
  slack:
    enabled: true
    notify_on: all # all | rejection | approval

Slack Message Preview

🏛️ MAGI Review Result

#42 feat: add user authentication

✅ Approved (2/3, 2 votes required)

🔬 MELCHIOR  ✅ approve
👩‍👧 BALTHASAR ⚠️ conditional
💃 CASPER    ✅ approve

[📋 View PR] [🔍 View Details]

💬 Debate Feature

When personas disagree, they debate and may change their votes.

Configuration

debate:
  enabled: true
  max_rounds: 1
  trigger: disagreement # conflict | disagreement | always
  revote_after_debate: true

Trigger Options

Trigger	Description
`conflict`	Only when both approve and reject exist
`disagreement`	When votes are not unanimous
`always`	Always debate (for testing)

Vote Changes

After debate, vote changes are shown as:

❌ reject → ⚠️ conditional
⚠️ conditional → ✅ approve

🎨 Persona Customization

Per-Persona Provider

Use different LLM providers for each persona:

personas:
  - id: melchior
    provider: openai
    model: gpt-5.2-pro
  - id: balthasar
    provider: claude
    model: claude-opus-4-5-20251101
  - id: casper
    provider: gemini
    model: gemini-2.5-flash

Note: Provide all required API keys when using per-persona providers. The action validates every referenced provider up front and fails fast with a clear error if a key is missing.

Common Guidelines

Create .github/magi/common.md to add guidelines for all personas:

# Team Guidelines

## Project Context

- This is an e-commerce platform
- PCI DSS compliance required

## Team Conventions

- All APIs follow REST conventions
- Error codes use ERR\_ prefix

Custom Persona Guidelines

Create .github/magi/melchior.md to fully customize individual personas.

Priority:

Custom guideline file (if exists)
Built-in default (fallback)
+ common.md (always appended)

📊 Output Example

## 🏛️ MAGI System Review Result

### ✅ Approved (2/3)

| Persona | Vote | Reason |
|:-------:|:----:|--------|
| 🔬 MELCHIOR | ✅ | Algorithm efficient, no security issues |
| 👩‍👧 BALTHASAR | ❌ reject → ⚠️ conditional | After debate: maintainability concerns addressed |
| 💃 CASPER | ✅ | UX consistency maintained |

<details>
<summary>🔬 MELCHIOR Details</summary>
...
</details>

📁 Project Structure

project-judge/
├── src/
│   ├── index.ts              # Main entry point
│   ├── config/               # Config loader & schema
│   ├── providers/            # LLM Providers (Gemini, OpenAI, Claude)
│   ├── personas/             # Personas & guidelines
│   │   └── built-in/         # Built-in defaults
│   ├── review/               # Review engine
│   ├── notifications/        # Slack notifications
│   └── github/               # GitHub API integration
├── action.yml                # GitHub Action metadata
└── .github/workflows/        # Example workflows

🔧 Development

# Install dependencies
pnpm install

# Type check
pnpm typecheck

# Build
pnpm build

# Test
pnpm test

📝 License

MIT

📖 한국어 문서 (Korean)

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
.github		.github
dist		dist
docs/superpowers/specs		docs/superpowers/specs
src		src
.gitignore		.gitignore
README.md		README.md
README_KO.md		README_KO.md
action.yml		action.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MAGI Review

🎭 Personas

🚀 Quick Start

Option 1: Gemini (Default)

Option 2: OpenAI (GPT-5)

Option 3: Claude (Anthropic)

Option 4: GCP Vertex AI (Enterprise)

Full Workflow Example

Comment-Triggered Re-Review

⚙️ Configuration

📱 Slack Notifications

Setup

Slack Message Preview

💬 Debate Feature

Configuration

Trigger Options

Vote Changes

🎨 Persona Customization

Per-Persona Provider

Common Guidelines

Custom Persona Guidelines

📊 Output Example

📁 Project Structure

🔧 Development

📝 License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

MAGI Review

🎭 Personas

🚀 Quick Start

Option 1: Gemini (Default)

Option 2: OpenAI (GPT-5)

Option 3: Claude (Anthropic)

Option 4: GCP Vertex AI (Enterprise)

Full Workflow Example

Comment-Triggered Re-Review

⚙️ Configuration

📱 Slack Notifications

Setup

Slack Message Preview

💬 Debate Feature

Configuration

Trigger Options

Vote Changes

🎨 Persona Customization

Per-Persona Provider

Common Guidelines

Custom Persona Guidelines

📊 Output Example

📁 Project Structure

🔧 Development

📝 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages