repo-readiness 0.1.2

GitHub repo launch-readiness auditor — signals your repo is missing for public discoverability.

repo-audit: GitHub repo launch-readiness checker

Your repo works locally. Now what? Most repos stay invisible not because the code is bad, but because no topics are set, no PyPI page exists, the README is three lines, and nobody has ever posted it anywhere.

repo-audit measures that gap in under 30 seconds and gives you a ranked to-do list you can act on immediately.

• "My repo has 0 stars and I don't know where to start."
• "I pushed a tool but it doesn't show up in GitHub search."
• "I want a quick audit before sharing a repo publicly."
• "I need to know what's missing before submitting to an awesome-* list."
• "I want to verify my launch checklist is actually done."

Install

pip install repo-audit

Requires Python 3.10+. No GitHub token needed.

Quick Start

repo-audit github.com/psf/black

Exact Outcome

repo-audit: github.com/psf/black
  Score: 91/100  Grade: A  (12.3s)

  PASS  README Quality         100/100
  PASS  Repo Metadata          100/100
  PASS  Social Proof           100/100
  PASS  Release Cadence        100/100
  PASS  Docs & Agent Files      90/100
  PASS  Distribution (PyPI/npm) 100/100
  PASS  Web Discoverability    100/100
  FAIL  Topical Citations       40/100
  WARN  Launch Channels         75/100

Top actions:
  [Topical Citations] Post 'Show HN: black — ...' at news.ycombinator.com.
  [Launch Channels] Submit a PR to the relevant awesome-* list.

Other Flags

# JSON output for scripting or CI
repo-audit github.com/psf/black --json

# Verbose: show per-signal findings and source URLs
repo-audit github.com/psf/black --verbose

Signal Categories

Signal	Weight	What it checks
README Quality	15%	length, quickstart, badges, license mention
Repo Metadata	12%	description, topics, homepage
Social Proof	10%	stars, forks, commit recency
Release Cadence	8%	GitHub releases and tags
Docs & Agent Files	10%	AGENTS.md, llms.txt, CONTRIBUTING, CHANGELOG
Distribution	15%	PyPI or npm presence
Web Discoverability	12%	DDG: does repo appear in top search results?
Topical Citations	10%	DDG: HN, Reddit, arXiv site: queries
Launch Channels	8%	awesome-* lists, DEV.to articles

When To Use It

• Before sharing a repo publicly (Show HN, blog post, tweet)
• Before submitting to an awesome-* list
• As a lightweight pre-launch CI check
• When auditing an existing repo to find quick wins

When Not To Use It

• To audit private repos (GitHub public API only, by design)
• To check code quality (use a linter for that)
• When you need proof of correctness, not a discoverability signal

Provenance Gate

Every signal in the output cites the GitHub API URL or search result URL it was derived from. No fabricated scores. When a signal can't be found (e.g. a private repo), the tool returns an honest null and cites the empty source URL.

Python API

from repo_audit.audit import run_audit
from repo_audit.formatter import format_text

report = run_audit("github.com/psf/black")
print(report.overall_score)   # int 0-100
print(report.grade)           # "A" | "B" | "C" | "D" | "F"
print(report.top_actions)     # list[str] ranked action items

License

Apache-2.0