readme-lies

Your README is lying. Your agent believes it.

11 real doc bugs found in httpx, pydantic, uv & typer · 83% precision on repos it had never seen

You clone a repo. The README says:

npm run dev

There is no dev script. There hasn't been for eight months. Someone renamed it to start and never touched the docs.

You shrug and go look at package.json. Your coding agent doesn't shrug. It runs the command, reads the error, guesses, tries three variations, and burns ten minutes of your tokens, because the README said so.

Docs don't rot loudly. They rot one renamed heading at a time. readme-lies checks every claim your docs make against the code, on every push.

What it catches

$ readme-lies
README.md:42: `npm run dev` — no "dev" script in package.json
README.md:77: […](docs/setup.md) — file does not exist
docs/api.md:12: […](#client-instances) — no heading with that anchor
docs/api.md:30: `createClient()` — `createClient` is not in the code (renamed or removed?)
4 lie(s) found.

It already found real bugs

I pointed it at 27 popular repositories and checked every finding by hand. These are live on main as I write this:

On 12 repos it had never seen during development, 10 of its 12 findings were real (83%). The other two taught it something, and every false alarm it has ever raised is now a regression test.

Add it to CI (30 seconds)

# .github/workflows/docs.yml
on: [push, pull_request]
jobs:
  readme-lies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sandeepsirodia/readme-lies@main

Lies show up as red annotations right on the PR diff, the moment someone renames the thing the docs point to.

Or just run it:

uvx --from git+https://github.com/sandeepsirodia/readme-lies readme-lies

Built to not cry wolf

A linter that's wrong twice gets uninstalled. So every rule stays quiet unless it's sure:

• npm run build inside a tutorial usually means the reader's project, not yours, so scripts are only checked in root docs and contributor guides. The same goes for anything after npm init, npx create-… or mkdir.
• yarn husky runs a binary, not a script. It's skipped.
• Gitignored files (generated API docs) are skipped.
• Docs-site routes like /guide/ and mkdocstrings pages are skipped.
• Setext headings, _emphasis_ in headings, CJK anchors, percent-encoding and {#custom-ids}: handled.

Still wrong? Put <!-- readme-lies-ignore --> on the line above and it'll look away.

readme-lies [paths…] [--root DIR] [--format text|github]

python -m unittest discover -s tests -v

Prior art, and what's new here

• lychee checks URLs (readme-lies deliberately doesn't).
• markdown-link-check and remark-validate-links check local links and headings. If that's all you need, they're mature choices.

readme-lies goes past links, to the claims docs make about the code:

• package scripts and make/just targets
• file paths in inline code
• functions that were renamed away (via git history)
• your CLI's own flags

It also handles the anchor rules of docs sites (VitePress, Docusaurus, mkdocs), not just GitHub's.

_{MIT © Sandeep Sirodia · Found a lie in your own README? A ⭐ is a nice way to say thanks.}