RealityLint: a static tool that checks whether your README still matches your repository

voonterr — Fri, 14 Aug 2026 22:14:23 +0000

README files often drift away from the projects they describe.

A script gets renamed. A file moves. .env.example disappears. The project switches package managers. But the README still confidently tells people to do the old thing.

I built RealityLint to catch this kind of drift automatically.

It’s a static, deterministic checker that compares locally verifiable README claims against the actual repository — without executing README commands.

What it can detect

RealityLint can catch things like:

missing npm / yarn / pnpm / bun scripts
broken local links and paths
missing .env.example / .env.sample files
package manager / lockfile mismatches
missing Python entry files
missing Makefile targets
outdated project version claims
license claims without a matching license file

Why I made it

I wanted something that helps keep documentation honest.

A lot of docs rot happens quietly:

setup instructions stop matching the repo
filenames change but docs don't
commands stay in the README long after they stop working

That kind of drift confuses users, contributors, and sometimes even the project owner.

Design goals

RealityLint was built to stay predictable:

no LLM
no API key
no source code upload
README commands are parsed but never executed
deterministic results
works locally and in GitHub Actions

Install

From PyPI:

pip install realitylint

Then run:

realitylint .

GitHub

Repository:

https://github.com/voonterr/realitylint

Current status

The project is already available on PyPI and can also be used as a GitHub Action.

Right now I’m especially interested in feedback on:

what README checks would be most useful next
what kinds of documentation drift you see most often
what would make this more useful in CI pipelines

If you’ve dealt with stale docs in your own projects, I’d love to hear what kinds of checks you wish existed.