github-first-impression 0.2.2

A rule-based audit of a public GitHub repository's presentation, documentation, installability, trust signals, and maintenance status

GitHub First Impression

What is it?

A deterministic quality gate for AI coding agents and maintainers auditing the presentation of public GitHub repositories.

Why?

Agents need a fast, predictable answer after changing a repository. GitHub First Impression applies transparent rules to documentation, installability signals, trust signals, releases, and maintenance indicators.

• Deterministic: every run produces the same score and audit decisions for the same repository state.
• Reproducible: rules and point allocations are public and contain no random component.
• Machine-readable: stable JSON fields and rule IDs support automation.
• CI-friendly: exit codes distinguish a passing gate, a failed gate, and a tool error.
• Bounded: it reads one public repository through GitHub's official REST API only.

It is not an AI reviewer, does not call an LLM, and does not analyze source-code quality. The score is a documentation and repository-presentation heuristic. It is not a code-quality, security, popularity, or maintainability guarantee.

Installation

For an isolated command-line installation:

pipx install github-first-impression

Or install it into the active Python environment:

python -m pip install github-first-impression

Python 3.12 or newer is required.

Quick example

github-first-impression \
  https://github.com/psf/requests \
  --format json \
  --fail-under 80

Selected fields from an actual run on August 3, 2026 are shown below. The full document also contains every category, scored check, and metadata; repository changes can change the result.

{
  "schema_version": "1.0",
  "tool": {
    "name": "github-first-impression",
    "version": "0.2.1"
  },
  "repository": {
    "url": "https://github.com/psf/requests",
    "owner": "psf",
    "name": "requests",
    "default_branch": "main",
    "archived": false
  },
  "result": {
    "status": "pass",
    "score": 86,
    "grade": "Good",
    "threshold": 80
  },
  "blocking_issues": [],
  "warnings": [
    {
      "id": "readme_contribution_guidance_missing",
      "check_id": "readme_has_contribution_guidance",
      "severity": "warning",
      "source": "repository",
      "message": "README does not mention contribution guidance.",
      "suggested_fix": "Link to contribution guidance from the README."
    }
  ],
  "artifacts": {
    "markdown_report": null
  }
}

Exit codes

Exit	Meaning
0	Quality gate passed
1	Quality gate failed
2	Tool error

An invalid input, GitHub API failure, network failure, or local I/O failure is a tool error. Parse the JSON on every exit code instead of treating all nonzero results alike.

Features

• Stable JSON output for agents and automated workflows
• Deterministic 100-point scoring with a configurable --fail-under threshold
• Prioritized blocking_issues when a repository misses the configured gate
• Stable category, check, issue, warning, and error IDs
• Explicit warning sources and concrete remediation suggestions
• Side-effect-free JSON mode unless a Markdown output path is requested
• CI-friendly exit codes and structured errors
• Optional Markdown reports for maintainers

Documentation

• Agent examples
• JSON output contract
• Publishing

Usage

Audit one public GitHub repository:

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

The module entry point is equivalent:

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

Text mode prints a terminal summary and creates first-impression-report.md. Use --output PATH to choose another report path or --output - to disable the Markdown report.

JSON mode has no Markdown side effect by default. Add --output report.md only when a Markdown artifact is wanted:

github-first-impression \
  https://github.com/owner/repository \
  --format json \
  --fail-under 80 \
  --output report.md

Use --verbose to include the full score breakdown in text-mode terminal output:

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

Optional GitHub token

GITHUB_TOKEN is optional. It increases GitHub's normal API rate limit but does not grant private-repository support or bypass access controls. Prefer the environment variable because command-line values may appear in shell history or process listings:

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

Use a token with no permissions beyond reading public repository information. The tool sends it only in the HTTPS Authorization header and does not include it in JSON or Markdown reports.

Scoring

The 100 available points are divided into five categories:

Category	Points
Project description and positioning	20
README readability	25
Installation and usage	20
Trust signals	20
Release and maintenance	15

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 for finding missing repository-presentation signals. It should not be used as an absolute ranking between unrelated projects.

Limitations

GitHub First Impression does not verify:

• Code correctness or architecture
• Security or exploitability
• Dependency vulnerabilities or supply-chain safety
• Legal compliance or license compatibility
• Whether a project is suitable for a particular user

Additional boundaries:

• README checks use headings, keywords, and regular expressions rather than semantic understanding.
• Non-English READMEs and unconventional headings may be underestimated.
• Information available only in external documentation may not earn README points.
• File presence does not prove that a policy, test suite, or configuration is effective.
• GitHub may truncate very large repository trees, causing files to be missed.
• Private repositories and bulk repository discovery are intentionally unsupported.

Responsible use

Each audit is initiated for one user-supplied public repository and uses only GitHub's official REST API. The tool does not access GitHub HTML, bypass access controls, evade rate limits, enumerate targets, or collect contributor profiles.

Read RESPONSIBLE_USE.md for the complete boundaries and token-safety guidance.

Development

git clone https://github.com/PiggyDoggo/GitHub-First-Impression.git
cd GitHub-First-Impression
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[development]"
python -m pytest

Build release artifacts with:

python -m build

Release notes are recorded in CHANGELOG.md.

License

GitHub First Impression is available under the MIT License.