Good Egg

Trust scoring for GitHub PR authors based on contribution history.

Why

AI has made mass pull requests trivial to generate, eroding the signal that a PR represents genuine investment. Good Egg is a data-driven answer: it mines a contributor's existing track record across the GitHub ecosystem instead of requiring manual vouching. See Methodology for the full approach or read the blog post for a higher-level overview.

Quick Start

Try Good Egg without installing anything (requires uv):

# Requires a GitHub personal access token
GITHUB_TOKEN=<token> uvx good-egg score <username> --repo <owner/repo>

This runs Good Egg in a temporary environment with no install needed.

Installation

pip install good-egg          # Core package
pip install good-egg[mcp]     # With MCP server support

GitHub Action

Add Good Egg to any pull request workflow:

name: Good Egg
on:
  pull_request:
    types: [opened, reopened, synchronize]
permissions:
  pull-requests: write
jobs:
  score:
    runs-on: ubuntu-latest
    steps:
      - uses: 2ndSetAI/good-egg@v0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Add checks: write to permissions if you enable check-run: true.

Example PR comment

See docs/github-action.md for inputs, outputs, and advanced configuration.

CLI

good-egg score <username> --repo <owner/repo>
good-egg score octocat --repo octocat/Hello-World --json
good-egg score octocat --repo octocat/Hello-World --verbose
good-egg cache-stats
good-egg cache-clear
good-egg --version
good-egg --help

Python Library

import asyncio
import os

from good_egg import score_pr_author

async def main() -> None:
    result = await score_pr_author(
        login="octocat",
        repo_owner="octocat",
        repo_name="Hello-World",
        token=os.environ["GITHUB_TOKEN"],
    )
    print(f"{result.trust_level}: {result.normalized_score:.2f}")

asyncio.run(main())

See docs/library.md for full API documentation.

MCP Server

pip install good-egg[mcp]
GITHUB_TOKEN=ghp_... good-egg-mcp

Add to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "good-egg": {
      "command": "good-egg-mcp",
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}

See docs/mcp-server.md for tool reference.

Scoring Models

Good Egg supports three scoring models:

v3 is the default. To use an older model, set scoring_model: v1 or scoring_model: v2 in your .good-egg.yml, pass --scoring-model v1 on the CLI, or set scoring-model: v1 in the action input. See Methodology for how each model works.

Fresh Egg Advisory

Accounts less than 365 days old receive a "Fresh Egg" advisory in the output. This is informational only and does not affect the score. Fresh accounts correlate with lower merge rates in the validation data.

How It Works

The default v3 model (Diet Egg) scores contributors by their alltime merge rate: merged PRs divided by total PRs (merged + closed). Older models (v1, v2) build a weighted contribution graph and run personalized graph scoring. See Methodology for details.

Trust Levels

Configuration

thresholds:
  high_trust: 0.7
  medium_trust: 0.3
graph_scoring:
  alpha: 0.85

Environment variables with the GOOD_EGG_ prefix can override individual settings. See docs/configuration.md for the full reference and examples/.good-egg.yml for a complete example.

Troubleshooting

See docs/troubleshooting.md for rate limits, required permissions, and common errors.

License

MIT

Egg image CC BY 2.0 (Flickr: renwest)