Maintainer Radar

GitHub Action and local CLI for read-only pull request triage reports.

Maintainer Radar helps you choose where to spend your next review session. It reads PR metadata, identifies likely blockers, and builds a plan around the time you have. You still review the code and decide what to do.

Try the interactive demo with a working example queue, or scan five recent PRs from a public repository. No installation or sign-in is needed for the demo.

Prefer a reproducible walkthrough? Compare a 15-minute and 30-minute session using a fictional two-PR queue, with the input, generated plans, and limits shown side by side.

What is in the queue	What Radar suggests
A small change with passing checks and tests	Start a review
A change with failing CI	Ask for the check failure to be addressed
A draft or running checks	Leave it waiting
More work than fits your session	Defer some PRs and keep a shorter plan

These are heuristics, not judgments about a contributor or the quality of their code. Every suggestion has a visible explanation. Radar does not post, label, approve, reject, or merge anything.

Quick Start

To get a report in GitHub, save this as .github/workflows/maintainer-radar.yml, commit it to your default branch, then run Maintainer Radar from the Actions tab. The report appears in the run summary. This uses the published v0.21.0:

name: Maintainer Radar
on:
  workflow_dispatch:
permissions:
  contents: read
  pull-requests: read
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@v7
        with:
          python-version: "3.12"
      - uses: JackSpiece/maintainer-radar@v0.21.0
        env:
          GH_TOKEN: ${{ github.token }}
        with:
          hydrate: "true"
          review-plan-minutes: "30"

For a local run, install the published source tag from GitHub:

python -m pip install "git+https://github.com/JackSpiece/maintainer-radar.git@v0.21.0"
gh auth login
maintainer-radar recommend https://github.com/owner/repo/pulls

Requires the GitHub CLI for authenticated live scans. Run gh auth login once.

To scaffold a config and scheduled workflow:

maintainer-radar init-repo --profile balanced

For stricter queue thresholds:

maintainer-radar init-config --profile strict --path .maintainer-radar.json

What It Does

It reads pull request metadata through the GitHub CLI, the GitHub Action token, or offline JSON, then reports:

• PRs that appear ready for review
• CI failures, merge conflicts, and author follow-up
• unresolved maintainer feedback
• transparent reviewability and risk signals
• a time-boxed review plan for the next session
• editable draft follow-ups that a maintainer can review before posting

Reports are available as Markdown, JSON, CSV, and standalone HTML. Version 0.21.0 can also save capture settings with JSON snapshots so offline comparisons call out changed scoring config, filters, or scan options. Version 0.21.0 adds local search and action filters to full, ungrouped HTML reports. Filtering changes visible rows without changing queue totals or scores, and makes no network requests.

Plan a review session

Use recommend for a short queue brief and suggested next command. To make a plan for a specific amount of time:

maintainer-radar repo owner/repo --hydrate --sort action --review-plan-minutes 30

The browser is a small public preview. Use the CLI with your authenticated gh session for a larger queue, private repositories you can access, or fuller review context. Estimates depend on PR metadata; they cannot know how familiar you are with the code.

Common Commands

# Queue brief for a repository
maintainer-radar repo owner/repo

# Deeper scan with pull request details
maintainer-radar repo owner/repo --hydrate --sort action

# Single pull request breakdown
maintainer-radar pr owner/repo 123

# Offline analysis
maintainer-radar from-json queue.json

# Short review-ready list
maintainer-radar repo owner/repo --action review-now --min-score 80 --top 10

Run maintainer-radar --help for the complete reference.

GitHub Action Outputs

The action exposes outputs for notifications, dashboards, and handoffs, including:

review-now, ci-blocked, merge-conflicts, branch-behind, maintainer-blocked, attention-level, workflow-mode, workflow-recommendation, and next-session-brief.

See GitHub Action usage and attention workflows.

Documentation

• Two minute quickstart
• Worked example with reproducible output
• Adoption guide
• GitHub Action
• Review plans
• Scoring heuristics
• Configuration
• Offline snapshot comparison
• Snapshot capture settings
• Local HTML report filters
• Privacy and permissions
• Project positioning
• GitLab JSON
• Forgejo and Gitea JSON

Contributing

Issues and focused pull requests are welcome. See CONTRIBUTING.md.

License

MIT