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

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.