good-egg 1.1.0

Trust scoring for GitHub contributors using graph-based ranking on contribution graphs

Good Egg

Trust scoring for GitHub PR authors using graph-based analysis of 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.

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 two scoring models:

Model	Name	Description
v1	Good Egg (default)	Graph-based scoring from contribution history
v2	Better Egg	Graph score + merge rate + account age via logistic regression

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

How It Works

Good Egg builds a weighted contribution graph from a user's merged PRs and runs personalized graph scoring to produce a trust score relative to your project. See Methodology for details.

Trust Levels

Level	Description
HIGH	Established contributor with a strong cross-project track record
MEDIUM	Some contribution history, but limited breadth or recency
LOW	Little to no prior contribution history -- review manually
UNKNOWN	Insufficient data to produce a meaningful score
BOT	Detected bot account (e.g. dependabot, renovate)
EXISTING_CONTRIBUTOR	Author already has merged PRs in this repo -- scoring skipped

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)