gh-analyzer

Before depending on an open-source library, you want to know if it's actively maintained, who owns the codebase, and whether issues get resolved. gh-analyzer answers that in seconds.

A command-line tool that scores GitHub repository health across commit momentum, bus factor, issue resolution, PR latency, and release cadence. Tested across Python 3.11, 3.12, and 3.13 with 61 unit tests.

Installation

pip install gh-analyzer

Requires Python 3.11+.

Quick start

gh-analyzer psf/requests
gh-analyzer tiangolo/fastapi --format table
gh-analyzer psf/requests --format json --output report.json

Authentication

Set a GitHub Personal Access Token to raise the rate limit from 60 to 5,000 requests/hour:

Mac/Linux:

export GITHUB_TOKEN=your_token_here

Windows:

set GITHUB_TOKEN=your_token_here

Without a token the tool is limited to 60 requests/hour and results may be incomplete.

Usage

gh-analyzer OWNER/REPO [options]

Options

Examples

gh-analyzer psf/requests
gh-analyzer psf/requests --since 90
gh-analyzer psf/requests --format json
gh-analyzer psf/requests --format json --output report.json
gh-analyzer psf/requests --format table
gh-analyzer torvalds/linux --since 30 --verbose
gh-analyzer psf/requests --ai-summary
gh-analyzer psf/requests --no-cache
gh-analyzer psf/requests --validate-token

Output

Text output (default)

Analyzing last 30 days (2026-05-16 to 2026-06-15)

psf/requests — A simple, yet elegant, HTTP library.
★ 54,041  ⑂ 9,969  229 open issues  Python

Commits
  Total commits        41
  Unique authors       14
  Most active author   nateprewitt (20 commits)
  Date range           2026-04-19 to 2026-06-09

  nateprewitt    20   ████████░  48.8%
  dependabot      6   ██░        14.6%
  jorenham        3   █░          7.3%

Issues
  Total issues         16
  Resolution rate      87.5%
  Avg resolution time  7.6h

Pull Requests
  Total PRs            129
  Merge rate           29.5%
  Avg time to merge    12.0h

Releases
  Latest tag           v2.34.2
  Days since release   31

Repository Health Score: 56/100  Grade C

  commit_momentum   ░░░░░░░░░░  4    30%    1.2
  bus_factor        ███████░░░ 73    25%   18.2
  issue_health      ████████░░ 88    20%   17.5
  pr_latency        ████████░░ 80    15%   12.0
  release_cadence   ███████░░░ 75    10%    7.5

Risk Assessment
  ✗ ERROR  MOMENTUM DROP: commit frequency down 68% vs prior period
  ✔ OK     ISSUE HEALTH: 88% resolution rate — maintainer is responsive

Table output (--format table)

Compact single-table summary — useful for quickly comparing multiple repos:

      psf/requests  30d (2026-05-16 to 2026-06-15)

  Signal            Value                        Score
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Commit momentum   41 commits (↓68%)                4
  Bus factor        HHI=0.273  top=49%              73
  Issue health      88% resolved (14/16)            88
  PR latency        12.0h avg merge                 80
  Release cadence   31d since last release          75

Health Score: 56/100  Grade C

JSON output (--format json)

{
  "repo": {
    "name": "requests",
    "full_name": "psf/requests",
    "description": "A simple, yet elegant, HTTP library.",
    "stars": 54041,
    "forks": 9969,
    "open_issues": 229,
    "language": "Python",
    "url": "https://github.com/psf/requests"
  },
  "analysis_window": {
    "days": 30,
    "from": "2026-05-16",
    "to": "2026-06-15"
  },
  "summary": {
    "commits": 41,
    "unique_authors": 14,
    "issues_total": 16,
    "issues_open": 2,
    "issues_closed": 14,
    "prs_total": 129,
    "prs_merged": 38,
    "releases_total": 3
  },
  "score": {
    "value": 56,
    "grade": "C",
    "components": [
      { "signal": "commit_momentum", "score": 4.09,  "weight": 0.3,  "effective_weight": 0.3,  "contribution": 1.23  },
      { "signal": "bus_factor",      "score": 72.69, "weight": 0.25, "effective_weight": 0.25, "contribution": 18.17 },
      { "signal": "issue_health",    "score": 87.5,  "weight": 0.2,  "effective_weight": 0.2,  "contribution": 17.5  },
      { "signal": "pr_latency",      "score": 80.0,  "weight": 0.15, "effective_weight": 0.15, "contribution": 12.0  },
      { "signal": "release_cadence", "score": 75.0,  "weight": 0.1,  "effective_weight": 0.1,  "contribution": 7.5   }
    ]
  },
  "bus_factor": {
    "hhi": 0.2731,
    "health_score": 72.69,
    "top_author": "nateprewitt",
    "top_author_pct": 48.8,
    "contributor_count": 14
  },
  "trend": {
    "commit_trend_pct": -67.74,
    "current_window": 10,
    "prior_window": 31,
    "low_confidence": false
  },
  "flags": [
    { "level": "ERROR", "code": "MOMENTUM_DROP_SEVERE", "message": "MOMENTUM DROP: commit frequency down 68% vs prior period" },
    { "level": "OK",    "code": "ISSUE_HEALTH_GOOD",    "message": "ISSUE HEALTH: 88% resolution rate — maintainer is responsive" }
  ],
  "ai_summary": null
}

Scoring Model

Bus factor uses the Herfindahl-Hirschman Index (HHI) to measure contributor concentration. HHI closer to 1.0 means one person dominates; closer to 0.0 means contributions are evenly distributed.

Missing signals (e.g. a repo with no releases) are excluded and weights are renormalized — the score always reflects available data honestly rather than penalizing repos for not using GitHub features.

Grades: A (80–100) · B (60–79) · C (40–59) · D (0–39)

Risk Flags

Each report includes risk flags sorted by severity:

Caching

API responses are cached at ~/.cache/gh-analyzer/ with a 5-minute TTL. Repeated runs within a session skip the network entirely. Use --no-cache to force a fresh fetch.

AI Summary

The --ai-summary flag appends a 3–4 sentence plain English interpretation of the health data, generated via the Gemini API. Requires GEMINI_API_KEY environment variable. The tool works normally without it.

export GEMINI_API_KEY=your_key_here   # Mac/Linux
set GEMINI_API_KEY=your_key_here      # Windows

Project Structure

gh-analyzer/
├── .github/
│   └── workflows/
│       └── test.yml          # GitHub Actions CI (Python 3.11, 3.12, 3.13)
├── gh_analyzer/
│   ├── main.py               # Entry point and fetch orchestration
│   ├── cli.py                # Argument parsing
│   ├── github_api.py         # Async GitHub API client with rate limit handling
│   ├── models.py             # Domain models
│   ├── exceptions.py         # Structured error types
│   ├── analytics.py          # Health scoring engine
│   ├── risk.py               # Risk flag detector
│   ├── ai_summary.py         # Gemini AI narrative summary
│   ├── reporter.py           # Rich terminal output and JSON serialization
│   └── cache.py              # Disk-based API response cache (5-min TTL)
├── tests/
│   ├── test_analytics.py     # 36 tests: HHI, scoring, edge cases
│   ├── test_risk.py          # 16 tests: all 12 risk flag rules
│   └── test_rate_limit_warning.py  # 9 tests: rate limit warning thresholds
├── pyproject.toml
└── README.md

Development

Clone the repo and install in development mode with Poetry:

git clone https://github.com/Alir3zag/gh-analyzer
cd gh-analyzer
poetry install --with dev

Run the test suite (61 tests):

poetry run pytest -v

Tests run automatically on every push via GitHub Actions across Python 3.11, 3.12, and 3.13.

License

MIT