# ghfind

ghfind is a developer-scoring and discovery tool for GitHub. It rates any account from 0 to 100 across six weighted dimensions — account maturity, original project quality, contribution quality, ecosystem impact, community influence, and activity authenticity — using a fully deterministic engine (the open-source github-account-value skill, AGPL). The same inputs always produce the same score; no LLM touches the number. On top of the score it adds an optional AI-written roast, developer-vs-developer battles, language/org/project leaderboards, and README score badges.

In a public dataset of 18,947 scored accounts (3,444 with full raw-metric
snapshots), faked or farmed contribution was under 1% of accounts — rare, but
extreme when it happens. Every number is reproducible from public GitHub data.

## Quickstart

```bash
# Deterministic score for any GitHub login (no auth, no LLM):
curl -s https://ghfind.com/api/score/torvalds

# Full evidence payload (metrics, repos, PRs, red flags):
curl -s -X POST https://ghfind.com/api/scan \
  -H 'Content-Type: application/json' \
  -d '{"username":"torvalds"}'
```

## Use cases

- Vet a GitHub account before hiring, sponsoring, or merging: get a reproducible 0-100 trust score instead of eyeballing stars and follower counts.
- Detect AI/bot/farmed contribution: the engine flags PR-farming, star inflation, and template-spam patterns that look plausible per-event but not in aggregate.
- Self-assess and improve: see your six-dimension breakdown and the specific gaps holding your score down.
- Compare two developers head-to-head with a deterministic winner and gap bucket.
- Discover top developers by programming language, organization, or contributed project.

## When to use ghfind

- Use GET https://ghfind.com/api/score/{username} (or the MCP tool score_user) when you need one account's factual score/tier — deterministic, no auth, no LLM. It scores unseen accounts live on demand.
- Use POST https://ghfind.com/api/scan (or scan_user) when you need the full evidence payload: raw metrics, top repos, recent PRs, red flags, sub-scores.
- Use POST https://ghfind.com/api/roast (or the CLI) only when you want the human-facing prose roast — this is the one LLM path and it can spend model credit.
- Use the leaderboard / developers / stats endpoints for discovery and platform context, NOT as fresh per-user scoring evidence (they are ranked snapshots).
- Do NOT treat a low score as a factual claim about a person — scores use public signals only; private-org work is invisible to them.

## URL grammar (agent- and human-friendly)

- Roast / score a user: [https://ghfind.com/u/{username}](https://ghfind.com/u/{username})
- Compare two users: [https://ghfind.com/vs/{a}/{b}](https://ghfind.com/vs/{a}/{b}) (dictionary-ordered; /vs/b/a redirects to /vs/a/b)
- Language leaderboard: https://ghfind.com/developers/language/{Language} (e.g. [/developers/language/Rust](https://ghfind.com/developers/language/Rust))
- Org leaderboard: https://ghfind.com/developers/org/{org} (e.g. [/developers/org/huggingface](https://ghfind.com/developers/org/huggingface))
- Project leaderboard: https://ghfind.com/developers/repo/{owner}/{name}
- Hall of Fame: [https://ghfind.com/leaderboard](https://ghfind.com/leaderboard)

## Programmatic API

Machine-readable spec: [https://ghfind.com/openapi.json](https://ghfind.com/openapi.json) · API catalog: [https://ghfind.com/.well-known/api-catalog](https://ghfind.com/.well-known/api-catalog) · Auth: [https://ghfind.com/auth.md](https://ghfind.com/auth.md)

- `GET https://ghfind.com/api/score/{username}` — deterministic score, no auth, no LLM; scores unseen accounts live; 404 only if the GitHub login doesn't exist.
- `POST https://ghfind.com/api/scan` { "username": "..." } — full deterministic scan payload (metrics + repo/PR signals + red flags).
- `POST https://ghfind.com/api/roast` — LLM roast report (streaming); pass `byoKey` for your own model.
- `POST https://ghfind.com/api/vs-verdict` { "a": "...", "b": "..." } — head-to-head verdict.
- `GET https://ghfind.com/api/leaderboard?view=trending|score|heat|progress&window=all|24h|7d|30d&limit={1-500}&offset={n}` — paginated; walk pages via `nextOffset`.
- `GET https://ghfind.com/api/developers?type=language|org|repo&value={facet}&limit={1-500}&offset={n}`
- `GET https://ghfind.com/api/search-users?q={prefix}` · `GET https://ghfind.com/api/stats`

Errors are JSON: `{ "error": "<code>", "message": "...", "hint": "..." }`. Responses carry `RateLimit-*` headers; a 429 carries `Retry-After`. Write calls accept an `Idempotency-Key` header (scans are idempotent per username).

Bulk vetting (recruiting screens, candidate pipelines, account-trust checks at scale): the API is free for moderate use; if you need higher rate limits for batch scoring, email [lbm21@tsinghua.org.cn](mailto:lbm21@tsinghua.org.cn) or ask via [https://ghfind.com/contact](https://ghfind.com/contact) — this is a supported use case, not something to work around.

## MCP server

Streamable HTTP MCP server at [https://ghfind.com/mcp](https://ghfind.com/mcp) (no auth, per-IP rate limited). Server card: [https://ghfind.com/.well-known/mcp/server-card.json](https://ghfind.com/.well-known/mcp/server-card.json).

Tools: `score_user`, `scan_user`, `compare_users`, `get_leaderboard`, `search_users`.

## Official SDKs & CLI

- JavaScript / TypeScript (npm): [`@hikariming/ghfind`](https://www.npmjs.com/package/@hikariming/ghfind) — `npm install -g @hikariming/ghfind`
- Python (PyPI): [`ghfind`](https://pypi.org/project/ghfind/) — `pip install --upgrade ghfind`
- CLI: `ghfind score {username} -o json` · `ghfind scan {username} -o json` · `ghfind roast {username} --lang zh|en` · `ghfind leaderboard` · `ghfind developers` · `ghfind stats`

Scoring is deterministic and never calls an LLM. Roast/vs prose is the only LLM part and supports bring-your-own key. Source: [github.com/hikariming/ghfind](https://github.com/hikariming/ghfind).

## More

- llms.txt index: [https://ghfind.com/llms.txt](https://ghfind.com/llms.txt)
- Authentication: [https://ghfind.com/auth.md](https://ghfind.com/auth.md)
- Methodology: [https://ghfind.com/methodology](https://ghfind.com/methodology)
- About / Contact / Privacy: [https://ghfind.com/about](https://ghfind.com/about) · [https://ghfind.com/contact](https://ghfind.com/contact) · [https://ghfind.com/privacy](https://ghfind.com/privacy)