GitHub First Impression

GitHub First Impression is a deterministic, rule-based command-line audit for public GitHub repositories.

It reviews repository presentation, README structure, installation and usage guidance, trust signals, releases, and maintenance indicators through GitHub's official REST API.

It can also act as a deterministic external quality gate after a coding agent pushes its work. Stable JSON output and process exit codes let automation distinguish a passing audit, a score below a configured threshold, and a tool error.

Important: The score is a documentation and repository-presentation heuristic. It is not a code-quality, security, popularity, or maintainability guarantee.

What it does

• Audits one user-supplied public repository at a time
• Checks repository metadata and README structure using deterministic rules
• Detects common installation, usage, community, packaging, release, and maintenance signals
• Produces a transparent score from 0 to 100
• Explains every awarded and missing score item
• Prints a concise terminal summary and writes a local Markdown report

What it does not do

• It does not understand source code or README prose like a human reviewer.
• It does not determine overall project quality, security, or suitability for use.
• It does not replace manual code review, security review, or maintenance due diligence.
• It does not access private repositories, discover targets, or scan repositories in bulk.
• It does not use AI, access GitHub HTML pages, or evade API limits and access controls.

Requirements

• Python 3.12 or newer
• Network access to GitHub's official REST API at api.github.com

Installation

Trusted Publishing has been verified on TestPyPI. The first production PyPI release is being prepared. Until then, install from the GitHub source or a GitHub Release checkout. See Trusted Publishing setup for the release process.

Clone the project and install it in a virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install .

Usage

After installation, audit a single public repository URL:

github-first-impression https://github.com/owner/repository

The module entry point is equivalent:

python -m github_first_impression https://github.com/owner/repository

In the default text mode, the command prints a summary and creates first-impression-report.md. Select another report path with --output PATH, or use --output - to print only the terminal summary without writing Markdown.

Using as an Agent Quality Gate

Request machine-readable output with:

github-first-impression \
  https://github.com/owner/repository \
  --format json

Set a deterministic minimum score from 0 to 100 with --fail-under:

github-first-impression \
  https://github.com/owner/repository \
  --format json \
  --fail-under 75

The command exits with 0 when the analysis passes, 1 when analysis succeeds but the score is below the configured threshold, and 2 for invalid input, API failures, network failures, or other tool errors. JSON mode writes exactly one JSON document to stdout; diagnostics are written to stderr.

JSON mode has no Markdown side effect by default, so it is safe in read-only CI workspaces and parallel Agent jobs. artifacts.markdown_report is null. Add --output report.md only when a Markdown artifact is wanted. --output - explicitly disables Markdown in either output format.

A shell workflow can preserve the structured result and handle each outcome separately:

set +e
github-first-impression "$REPOSITORY_URL" \
  --format json \
  --fail-under 75 \
  > audit.json
exit_code=$?
set -e

case "$exit_code" in
  0) echo "Quality gate passed" ;;
  1) echo "Quality gate failed; inspect audit.json" ;;
  2) echo "Audit tool error; inspect audit.json and stderr" ;;
esac

The set +e section preserves exit code 1 in scripts that otherwise use set -e.

Agents should not act on the total score alone. Read the stable rule IDs in categories[].checks, address blocking_issues, review warnings, push the fixes, and run the audit again. Blocking issues are only the highest-priority score deficits, not proof of an absolute defect and not a promise that fixing them alone will pass the threshold. Warning source distinguishes repository observations from analysis limitations. This is an external presentation and documentation heuristic—not a guarantee of code correctness, security, maintainability, or legal compliance.

The JSON contract is documented in docs/json-output.md.

Optional GitHub token

Using GITHUB_TOKEN is optional. A token increases the normal API rate limit but is not used to bypass GitHub's restrictions. Prefer the environment variable because a command-line argument may be visible in shell history or process listings:

export GITHUB_TOKEN="your_token"
github-first-impression https://github.com/owner/repository

The less-private command-line alternative is also available:

github-first-impression https://github.com/owner/repository --token "your_token"

Use a token with no permissions beyond reading public repository information. The tool sends it only in the HTTPS Authorization header. It does not print, save, cache, rotate, place it in a URL, or include it in a report.

Verbose score breakdown

Use --verbose to display every score item in the terminal. Markdown reports always include the complete breakdown.

github-first-impression https://github.com/owner/repository --verbose

Example output format

The repository name and numbers below are illustrative placeholders, not the current result for a real repository:

GITHUB FIRST IMPRESSION
=======================
Repository: example/example-repository
Overall Score: 78/100
Grade: Good

Category scores:
- Project description & positioning: 18/20
- README readability: 20/25
- Installation & usage: 16/20
- Project trust: 14/20
- Release & maintenance: 10/15

Run with --verbose to see the full score breakdown.

Markdown report written to first-impression-report.md

Scoring

The 100 available points are divided into five categories:

The score is produced entirely by deterministic rules in src/github_first_impression/scoring.py; it contains no random component. The same repository state and README will usually produce the same result. A score can change when repository metadata, files, documentation, releases, tags, or maintenance activity change.

Grades are Excellent (90–100), Good (75–89), Fair (60–74), Weak (40–59), and Poor (0–39). These labels summarize checklist coverage, not intrinsic project quality.

The score is most useful as a checklist for repository maintainers. It should not be used as an absolute ranking between unrelated projects. In particular:

• Non-English READMEs and unconventional heading names may be underestimated.
• Information found only in external documentation may not earn README points.
• A mature project with a deliberately minimal root README may receive a relatively low score.
• A high score does not establish code quality, security, active maintenance, popularity, or fitness for a particular purpose.

Known limitations

• README checks use headings, keywords, and regular expressions rather than semantic understanding.
• File presence does not prove that a policy, test suite, or configuration is complete or effective.
• GitHub can truncate recursive trees for extremely large repositories, causing files to be missed.
• “Recently updated” means a code push within two years and is only a broad activity signal.
• GitHub's open issue count can include open pull requests.
• Anonymous API access has a lower rate limit. The client stops on a rate-limit response and does not retry, change identity, or fall back to HTML access.
• Private repositories are intentionally unsupported.
• JSON schema 1.0 describes repository presentation signals only; it does not make source-code assertions.

Responsible Use

Each audit is initiated by the user for one specific public repository and is performed only through GitHub's official REST API. Reports are generated locally. The tool does not access GitHub web pages, bypass access controls, evade rate limits, enumerate repositories, or collect contributor profiles.

Repository content remains subject to its original license and copyright terms. Users are responsible for following GitHub's Terms of Service and applicable laws. Read RESPONSIBLE_USE.md for the complete boundaries and token-safety guidance.

Development

Create a development environment and install the optional tooling:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[development]"

Running tests

python -m pytest

Build release artifacts with:

python -m build

Changelog

Release notes are recorded in CHANGELOG.md.

License

GitHub First Impression is available under the MIT License.