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

Compare projects

Pass two or more URLs to compare them side by side — e.g. to pick between similar libraries:

gh-score https://github.com/fastapi/fastapi https://github.com/pallets/flask https://github.com/django/django
gh-score --format markdown https://github.com/BurntSushi/ripgrep https://github.com/sharkdp/fd

The comparison checks that it is credible: each pair is assessed for subject comparability (shared topics / description keywords), language compatibility for libraries, and library-vs-application mismatches. Non-credible pairs are flagged with the reason — warnings never block the comparison.

The output is a decision table: one line per project (stars, license, language, maintenance state, last commit, bus factor, downloads, latest release, traffic-light verdict), ranked by verdict, then downloads, then bus factor. Each pair also shows an informational similarity score (0.0–1.0) saying how close the expressed subjects are.

Search, then score

Don't know the repository name yet? Search GitHub, filter the noise, and score the ones worth a look:

# Find candidates (one API request, no analysis)
gh-score search vega mcp --lang py --no-analyze

# Analyze the first 5, removing the polysemy by hand
gh-score search vega mcp --lang py --not vegas --not vega-os --not vegapunk --limit 5

Relevance and health are kept apart: the filter decides which projects match, the analysis decides how healthy they are — and never the other way round. Every dropped candidate is listed with its reason, so the filter is auditable instead of magic.

GitHub's search matches prefixes, which is why --lang is resolved locally (py → Python) and why --not is the only reliable way to remove a meaning you did not want.

--lang js covers both JavaScript and TypeScript (GitHub ORs the qualifiers in a single request): a tool rewritten in TypeScript is still a JavaScript tool. --lang is repeatable and accepts comma-separated values.

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

Reasoning models (Qwen-style "thinking", DeepSeek R1, …) spend the whole token budget on chain-of-thought and get cut off before emitting the JSON. If your model produces "empty or unparseable JSON response" warnings, disable the reasoning pass:

export GH_SCORE_LLM_DISABLE_REASONING=true

The provider then asks the server to skip reasoning (chat_template_kwargs.enable_thinking: false, honored by oMLX / vLLM / llama.cpp-style servers, plus the OpenAI-compatible reasoning_effort: "none"). Opt-in: only set it for reasoning models.

Configuration

Set a GH_SCORE_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.

gh-score reads settings from the environment and from config.toml only: it never loads a .env file. Export the variables yourself.

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.