# RepoFather

<p align="center">
  <img src="./assets/repofather-hero.png" alt="RepoFather manipulating repository graphs on transparent ASCII screens" width="100%">
</p>

[![ci](https://github.com/its-imad/RepoFather/actions/workflows/ci.yml/badge.svg)](https://github.com/its-imad/RepoFather/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/repofather-mcp)](https://www.npmjs.com/package/repofather-mcp)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

RepoFather is an open-source growth and trust-readiness radar for maintainers. It finds why strangers do not try, star, share, contribute to, fund, or trust a repo, then gives the next moves to make the project harder to ignore.

It scans the files in a repository and returns a growth diagnosis: what is already working, what is missing, why people may bounce, which stronger repos to learn from, and what to fix inside and outside the repo. It also checks trust and compliance-readiness signals such as privacy, security reporting, AI disclosure, GDPR-oriented data handling, EU AI Act role/risk notes, SOC 2 path, and procurement readiness. The score is still there, but it supports the growth workflow instead of being the whole product.

RepoFather does not call an AI model to score your repo. The CLI and MCP tool return deterministic, evidence-based reports from repo files, package metadata, and submitted snapshots. AI is useful around RepoFather: Codex, Claude, Cursor, or another MCP client can call RepoFather, read the report, explain the tradeoffs, and help apply the fixes.

## Quick Start

Most users should start with the Growth Radar. Run this inside any repository you want to improve:

```bash
npx -p repofather-mcp repofather growth .
```

Write the growth radar to `REPOFATHER_GROWTH.md`:

```bash
npx -p repofather-mcp repofather growth . --write
```

Inspect the 1,000+ internal growth-signal catalog:

```bash
npx -p repofather-mcp repofather growth . --advanced
npx -p repofather-mcp repofather growth . --all
```

Get the compact score underneath the growth diagnosis:

```bash
npx -p repofather-mcp repofather scan .
```

Generate the action-first launch rescue report:

```bash
npx -p repofather-mcp repofather report .
```

Generate the compact context pack an AI agent should use before editing the repo:

```bash
npx -p repofather-mcp repofather context .
```

Generate the trust and compliance-readiness report:

```bash
npx -p repofather-mcp repofather compliance .
```

Compare your repo against similar or successful repos:

```bash
npx -p repofather-mcp repofather benchmark . --against upstash/context7
```

`opportunities` is kept as a longer alias for `growth`:

```bash
npx -p repofather-mcp repofather opportunities .
```

You can benchmark against local paths too:

```bash
npx -p repofather-mcp repofather benchmark . --against ../other-devtool
```

Generate Hacker News, Reddit, X, badge, topic, and sponsor-tier ideas:

```bash
npx -p repofather-mcp repofather assets .
```

Return JSON for scripts or automation:

```bash
npx -p repofather-mcp repofather scan . --json
npx -p repofather-mcp repofather growth . --json
npx -p repofather-mcp repofather growth . --advanced --json
npx -p repofather-mcp repofather report . --json
npx -p repofather-mcp repofather context . --json
npx -p repofather-mcp repofather compliance . --json
npx -p repofather-mcp repofather benchmark . --against upstash/context7 --json
```

Install it globally if you want a shorter command:

```bash
npm install -g repofather-mcp
repofather growth .
```

For local development:

```bash
npm install
npm run catalog:generate
npm test
npm run build
```

## What It Checks

RepoFather scores six areas:

- **Positioning** - name, README opening, audience, differentiation, and MCP/OSS positioning.
- **Tryability** - install command, quickstart, examples, tests, real screenshots, GIFs, videos, or live demo links.
- **Community** - license, contributing guide, issue templates, CI, and roadmap.
- **MCP readiness** - documented endpoint, tools, client setup, remote deployment, and privacy/security notes.
- **Monetization readiness** - sponsor path, open-core boundary, hosted/team upgrade path, badges, metrics, or API surfaces.
- **Virality** - memorable name, repeatable hook, painful problem, launch channels, and built-in sharing loop.

The output is designed to be fixable. RepoFather does not just say a repo is weak; it tells you what to add next.

Demo scoring is evidence-based. Mentioning the word "demo" is not enough; RepoFather looks for a referenced media asset in the snapshot, a visual asset in the repo paired with screenshot/demo wording, or a live demo/video URL.

Critical adoption gaps can cap the overall score. For example, a repo without visible proof cannot reach the Magnetic band even if the rest of the checklist is strong. The Growth Radar then turns those findings into the next repo, package, distribution, brand, and analytics moves.

Trust and compliance readiness is reported separately from legal compliance. RepoFather can flag missing privacy, security, AI, GDPR, EU AI Act, SOC 2, and procurement evidence, but it does not certify compliance or replace legal, security, or audit review.

## Launch Rescue Report

`repofather report .` is the painkiller workflow. It turns the score into an action plan:

- why strangers may bounce
- highest-impact fixes ranked by adoption risk, not just checklist points
- suggested README opening rewrite
- launch readiness for Hacker News, Reddit, Product Hunt, GitHub, and LinkedIn
- HN and Reddit launch drafts
- first-hour checklist before posting publicly

Example excerpt:

```text
Painkiller score: 92/100

Why Strangers May Bounce
- There is no concrete visual proof or live demo, so people have to imagine the result instead of seeing it.

Fix These First
1. Add proof people can see before they install
   - Next step: Record a 45-60 second demo showing install, first command, and useful output.

Launch Channel Readiness
- Hacker News: 80/100, almost. Missing: demo GIF, screenshot, video, or live demo.
- Reddit: 85/100, ready. Missing: proof that makes the post feel non-promotional.
```

## Context And Benchmarks

`repofather context .` produces the compact repo intelligence pack an AI agent should use before changing your README, package metadata, launch copy, or issue templates.

It includes:

- audience, main pain, launch line, and proof status
- top adoption blockers
- strongest repo evidence
- next best actions
- best first launch channel
- guardrails so agents do not invent screenshots, social proof, hosted products, or funding paths

`repofather benchmark . --against owner/repo` compares your repo with a stronger or similar repo. Stars are treated as distribution context, not the score. RepoFather compares launch surfaces: README structure, proof, examples, install path, community files, MCP readiness, monetization path, virality loop, and channel fit.

Example:

```text
Benchmark: repomother
Stars/day: 714.29

Closest gaps:
1. Add proof people can see before they install
   - Benchmark signal: repomother passes this signal.
   - Next step: Record a 45-60 second demo showing install, first command, and useful output.
```

## Growth Radar

`repofather growth .` is the flagship workflow. It keeps the core score honest while adding a broader catalog of growth signals. It checks repo evidence and flags external work that cannot be proven from local files.

RepoFather now has a source-generated catalog with more than 1,000 internal growth signals behind the default report. The default mode stays focused on the most actionable next moves. `--advanced` adds the broad maintainer-growth catalog across DX, docs, tooling, integrations, quality, community, launch ops, package surfaces, AI/agent readiness, and monetization. `--all` shows the complete catalog, including future-stage or higher-risk enterprise, telemetry, licensing, procurement, compliance, and distribution levers.

It covers:

- repo conversion: opening, pain, hook, install, quickstart, examples, FAQ, architecture, roadmap, changelog
- proof: screenshots, GIFs, videos, live demos, before/after contrast, real output, social proof, benchmark story
- DX and tooling: time to first success, zero-config defaults, actionable errors, devcontainers, Docker Compose, hot reload
- docs: dedicated site, playground, search, recipes, generated API docs, localization, dark mode
- community trust: license, contributing guide, issue templates, PR template, code of conduct, security policy, CI, tests, funding, starter issues
- package readiness: npm description, keywords, binary, homepage, repository and bug URLs, package files, version
- agent readiness: MCP endpoint, tool names, client setup, and agent rule paths
- integrations and enterprise: GitHub App, Slack/Discord, database adapters, SSO, RBAC, audit logs, Helm, Terraform, SBOMs, signing
- distribution and launch ops: Hacker News, Reddit, Product Hunt, awesome lists, MCP directories, package managers, blog posts, creator outreach, newsletters
- brand, analytics, and telemetry: domain ideas, score badge, public score pages, history, privacy, release loops, opt-in analytics, UTM tracking

External and manual signals are deliberately separate from the score. RepoFather suggests domain candidates like `yourproject.dev`, `yourproject.io`, `yourproject.app`, and `yourproject.ai`, but it does not claim availability without a live registrar or DNS check.

`repofather opportunities .` remains available as an alias for the same report.

The catalog source lives in `catalog/packs.json`. `npm run catalog:generate` validates and expands those packs into `src/generated-growth-catalog.ts`, which is bundled for the CLI, npm package, MCP server, and Worker.

## Trust And Compliance Readiness

`repofather compliance .` is a deterministic readiness report for trust signals that buyers, users, security reviewers, and counsel often ask about.

It checks for evidence around:

- privacy policy or privacy notice
- data handling scope, retention, deletion, and personal-data language
- subprocessors, vendors, DPA, and processor/controller path
- security policy and vulnerability reporting contact
- AI usage disclosure and AI data boundary
- EU AI Act role/risk note, transparency, and use-boundary language
- SOC 2 path, audit logs, access control, and procurement readiness
- overclaim guardrails so the repo does not casually say "GDPR compliant", "EU AI Act compliant", or "SOC 2 certified"

Example:

```bash
npx -p repofather-mcp repofather compliance . --write
```

This writes `REPOFATHER_COMPLIANCE.md`.

Important: this is not legal advice, not SOC 2 evidence, and not a compliance certification. It is a readiness layer that helps maintainers see what trust questions the repo does or does not answer yet.

## AI, MCP, And Trust

RepoFather separates deterministic scoring from AI-assisted work:

- **CLI mode:** `repofather growth .` runs locally and does not use AI. It reads the repository snapshot and applies explicit scoring rules.
- **MCP mode:** RepoFather still does not use AI internally. It exposes tools that an AI client can call.
- **AI client:** Codex, Claude, Cursor, or another client can interpret RepoFather's JSON/Markdown output, prioritize fixes, edit files, or draft launch copy.

That split is deliberate. Scores should be repeatable and debatable. AI can help with judgment, writing, and implementation after RepoFather has produced the evidence.

## Score Output

```text
RepoFather score: 76/100 (Launchable)

Buckets
- positioning: 80/100
- tryability: 75/100
- community: 70/100
- mcp: 90/100
- monetization: 65/100
- virality: 80/100

Strong signals
- One-command install is visible
- License is present
- MCP endpoint/server is documented

Top fixes
- Add a 60-second demo GIF or screenshot
- Add a public roadmap
- Explain the free core vs paid hosted/team features
```

## MCP Server

RepoFather also runs as a remote MCP server:

```text
https://repofather-mcp.nocodepiper.workers.dev/mcp
```

Use the MCP server when you want an AI client to call RepoFather tools. Use the CLI when you want to run the growth radar locally. In both cases, RepoFather's scoring engine is deterministic; the AI lives in the client that calls it.

Available tools:

- `growth_report` - generate the flagship growth radar with repo, package, proof, distribution, listing, community, brand, analytics, domain-check, and 1,000+ catalog opportunities. Pass `mode: "advanced"` or `mode: "all"` for the deeper catalog.
- `score_repository_snapshot` - score a repository snapshot submitted by an MCP client.
- `launch_rescue_report` - generate the action-first launch rescue report as Markdown or JSON.
- `repo_context_pack` - generate the compact agent context pack.
- `benchmark_repository_snapshot` - compare a repo snapshot with benchmark snapshots.
- `compliance_readiness_report` - generate the deterministic trust and compliance-readiness report for privacy, security, AI disclosure, GDPR, EU AI Act, SOC 2 path, and procurement evidence.
- `growth_opportunity_report` - backward-compatible alias for the growth radar.
- `generate_launch_assets` - produce Hacker News, Reddit, X, README badge text, topics, and sponsor-tier ideas.
- `monetization_ladder` - map an open-core project into free, solo, team, and enterprise layers.

### Codex

Codex supports remote streamable HTTP MCP servers directly:

```bash
codex mcp add repofather --url https://repofather-mcp.nocodepiper.workers.dev/mcp
```

Restart Codex after adding the server. Then ask Codex to use RepoFather to score or improve a repository.

### Claude Desktop

Add RepoFather to your Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "repofather": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://repofather-mcp.nocodepiper.workers.dev/mcp"
      ]
    }
  }
}
```

Restart Claude Desktop after saving the config.

### Cursor, Windsurf, and Other MCP Clients

Use this command and argument pair in any MCP client that supports stdio servers:

```text
command: npx
args: mcp-remote https://repofather-mcp.nocodepiper.workers.dev/mcp
```

Some clients ask for JSON instead:

```json
{
  "command": "npx",
  "args": [
    "mcp-remote",
    "https://repofather-mcp.nocodepiper.workers.dev/mcp"
  ]
}
```

Restart the client after adding the server.

### Testing The MCP Bridge Manually

You can test the remote MCP bridge from a terminal:

```bash
npx mcp-remote https://repofather-mcp.nocodepiper.workers.dev/mcp
```

If it prints something like `Proxy established successfully between local STDIO and remote StreamableHTTPClientTransport`, the connection works.

This command is expected to keep running. It is a bridge for MCP clients, not an interactive CLI. Press `Ctrl+C` to stop it.

## Troubleshooting

### `npx mcp-remote ...` looks stuck

That is normal. `mcp-remote` starts a local stdio bridge and waits for an MCP client to send requests. It will not print a RepoFather score by itself.

For the terminal growth radar, use:

```bash
npx -p repofather-mcp repofather growth .
```

### `repofather: command not found`

Use the package form:

```bash
npx -p repofather-mcp repofather growth .
```

Or install globally:

```bash
npm install -g repofather-mcp
repofather growth .
```

### Which command should I use?

- Use `repofather growth .` when you want the main growth radar: adoption blockers, proof gaps, distribution/listing work, package metadata, domains, and next actions.
- Use `repofather growth . --write` when you want to save `REPOFATHER_GROWTH.md`.
- Use `repofather growth . --advanced` when you want the broad practical growth-signal catalog.
- Use `repofather growth . --all` when you want every 1,000+ catalog item, including future-stage and higher-risk levers.
- Use `repofather scan .` when you only want the compact score in the terminal.
- Use `repofather report .` when you want the launch rescue report with bounce reasons, fixes, channel readiness, and launch drafts.
- Use `repofather report . --write` when you want to save `REPOFATHER_REPORT.md`.
- Use `repofather context .` when you want an agent-ready context pack before asking AI to improve the repo.
- Use `repofather compliance .` when you want trust and compliance-readiness gaps without legal or audit claims.
- Use `repofather benchmark . --against owner/repo` when you want to compare against a similar successful repo.
- Use `repofather opportunities .` when you want the older alias for `growth`.
- Use `repofather assets .` when you want Hacker News, Reddit, X, badge, topic, and sponsor-tier ideas.
- Use the MCP endpoint when you want Codex, Claude, Cursor, or another MCP client to call RepoFather as a tool.
- Use `npx mcp-remote ...` only when your MCP client needs a local stdio bridge.

## Local MCP Development

Run the Cloudflare Worker locally:

```bash
npm run dev
```

Local MCP endpoint:

```text
http://localhost:8787/mcp
```

Deploy:

```bash
npm run build
npx wrangler deploy
```

## Why RepoFather

Useful open-source projects often lose attention for boring reasons: the README does not explain the promise, the install path is unclear, the demo is missing, contributors do not know where to start, or the paid path feels awkward.

RepoFather is deliberately not just a README scorer. It turns repo evidence into a growth radar, rescue report, benchmark, and launch assets so maintainers can make the project more credible before asking people to star, install, sponsor, or adopt it.

## Open Core

The CLI and MCP server are open source.

Future hosted features can build on top of the same scoring rules:

- public score pages and badges
- historical score tracking
- private GitHub app scans
- auto-created GitHub issues from failed checks
- launch calendars and saved social drafts
- team policies for release readiness

## Roadmap

- `0.1` - CLI scanner, launch rescue report, context pack, benchmark report, trust/compliance readiness report, 1,000+ signal growth radar, launch asset generator, and remote MCP server.
- `0.2` - GitHub Action, badge JSON endpoint, and sharper growth command ergonomics.
- `0.3` - hosted public scan pages.
- `0.4` - private GitHub app scans and score history.
- `0.5` - optional underrated OSS discovery radar built from compliant public data sources.
- `1.0` - team dashboards, org policies, and API.

## License

MIT