gh-score

GitHub Project Health Scorer — evaluate maturity, maintenance, community health and sustainability of any GitHub project, in your terminal.

gh-score turns raw GitHub signals (commit activity, contributors, releases, license, registries, sustainability) into a single traffic-light verdict: 🟢 green (safe to bet on), 🟠 orange (proceed with caution), 🔴 red (risky).

When a repository declares a homepage, gh-score also checks that the application's web page is actually reachable — DNS resolution, timeouts, HTTP status (redirects followed) — and flags pages hidden behind a bot-protection check ("I'm not a robot"). A dead homepage is a red flag for the verdict.

Usage

# Analyze a remote repository (no install needed)
uvx gh-score https://github.com/owner/repo

# Analyze the current directory (if it's a git clone)
uvx gh-score

# Or install it
pip install gh-score
gh-score https://github.com/owner/repo

Output formats

gh-score --format tui       https://github.com/owner/repo   # terminal dashboard (default)
gh-score --format markdown  https://github.com/owner/repo   # Markdown report
gh-score --format json      https://github.com/owner/repo   # structured JSON

Optional LLM analysis

The LLM is opt-in and never required. It extracts qualitative facts that cannot be derived from APIs or files (roadmap, commercial support, security policy, self-declared maintenance state) and produces a refined, complementary recommendation that weighs all indicators together.

export GH_SCORE_LLM_ENABLED=true
export GH_SCORE_LLM_BASE_URL="https://api.openai.com/v1"   # any OpenAI-compatible API
export GH_SCORE_LLM_MODEL="gpt-4o-mini"
export GH_SCORE_LLM_API_KEY="sk-..."
gh-score https://github.com/owner/repo

Configuration

Set a GITHUB_TOKEN to raise API rate limits. LLM settings can also live in a config.toml (see gh-score config). Everything stays optional: the tool works fully offline with local clones and no token.

To enrich the report with dependents counts (how many packages depend on this library) for PyPI, npm and Maven — the only ecosystems whose official registries expose no reverse-dependency count — set a free libraries.io API key (60 requests/minute):

export LIBRARIES_IO_API_KEY="..."
# or in config.toml:
# [registries]
# libraries_io_api_key = "..."

crates.io, RubyGems and Go (pkg.go.dev) always provide their own dependents count; downloads are always fetched where the registry exposes them.

Library

from gh_score import analyze_repo

result = analyze_repo("https://github.com/owner/repo")
print(result.recommendation.level)          # RecommendationLevel.GREEN
print(result.release_health.latest_version) # "v1.0.0"
print(result.contributors.bus_factor)       # 3

Screenshot

License

GPL-3.0 — see LICENSE.