Name a public GitHub repository or paste a README. You get a score from 0 to 100 on a published rubric, the fixes worth the most points first, and a comparison against 2,069 repositories we analysed for the README Benchmark. No signup, and the whole result is on the page.
The score is a weighted checklist. Each category below is scored from 0 to 100 by the checks it contains, and the overall score is the categories combined by weight. Every check reads one feature our extractor detects in the markdown, so the same README always gets the same score and every point can be traced to the check that gave it.
| Category | Weight | Checks (points within the category) |
|---|---|---|
| Value proposition and clarity | 20% |
|
| Installation and setup | 20% |
|
| Usage examples | 15% |
|
| Documentation structure | 15% |
|
| Target audience and use cases | 10% |
|
| Contribution guidelines | 10% |
|
| Calls to action and project links | 10% |
|
One check gives partial credit: the opening sentence earns all 40 points within the first 200 characters, 24 within 400 and 10 within 900. Every other check is met or not.
It is a heuristic. The weights are our judgement about what a first-time reader needs, written down so you can disagree with them. Nobody has shown that a README scoring 80 gets more users than one scoring 60, and we do not claim it.
The measured number is the comparison beside it: a count against a fixed thirteen-item checklist, and where that count sits among 2,069 real repositories. When the result says a README is more complete than 62% of them, that figure was computed the same way for both sides of the comparison. Below the score, six areas are also rated against the benchmark, with the evidence for each rating.
No language model is involved at any point, which is also why this is free and why two runs over an unchanged README give the same answer.
It answers the questions a first-time reader has, in the order they have them: what is this, is it for me, how do I install it, what does using it look like, and where do I go next. The first of those has to be answered in the first screen, before badges and logos.
In the 2,069 repositories we measured, about six in ten have installation instructions, about a third state their licence in the README, and around nine in ten never say who the project is for.
Seven categories, each with a fixed weight, each made of a few checks worth fixed points. Every check reads one feature our pattern-based extractor detects in the markdown, such as an installation section or a link to documentation. The category scores are combined by weight into a number from 0 to 100.
The same README always gets the same score, no language model is involved, and the full rubric is published on this page.
Not necessarily. The rubric is a judgement about what a first-time reader needs, written down so you can check it. Nobody has shown that a README scoring 80 attracts more users than one scoring 60. The benchmark comparison shown beside the score is measured, but it is observational too: popular projects tend to have these sections, which is not proof that adding them causes growth.
No. Pasted markdown is graded in memory and discarded. We record that a grade happened and its score, for counting how the tool is used, but not the text. A pasted result also has no shareable link, because there is nothing stored to link to.
Not by URL: the tool only reads public repositories, and it reports a private one the same way as one that does not exist. You can paste a private README into the paste tab instead.
Related: how to improve your README · open-source launch planner · a README audit in your coding agent (Orviqa Lite) · the benchmark behind this tool · what a README has to do in ten seconds · promoting an open-source project