repo-readiness 0.8.0

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

repo-readiness: 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-readiness

Requires Python 3.10+.

Migration: previously published as hermes-repo-audit on PyPI. Install the new name going forward. The binary is still repo-audit (plus a new repo-readiness alias).

Quick Start

repo-audit github.com/psf/black
# or, equivalently:
repo-readiness 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, source URLs, and auth mode
repo-audit github.com/psf/black --verbose

# Explicit GitHub token (overrides env + gh CLI)
repo-audit github.com/psf/black --token ghp_xxx

Authentication

Unauthenticated GitHub API calls are capped at 60/hr — enough for a single audit, but a portfolio-wide batch will rate-limit.

repo-audit resolves a token in this order:

1. --token <t> CLI flag (explicit).
2. GITHUB_TOKEN or GH_TOKEN environment variable.
3. gh auth token (if the GitHub CLI is installed and logged in).
4. Unauthenticated (60 req/hr, retries once on 403).

Run with --verbose to see which mode was used:

$ repo-audit some-org/some-repo --verbose
[auth] mode=gh-cli

Authenticated calls get 5,000 req/hr — enough for a 21-repo batch in seconds.

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

Changelog

See CHANGELOG.md for release history.

License

Apache-2.0