RealityLint

Your README says it works. RealityLint checks if it actually does.

Static, deterministic README-vs-repository verification — without executing README commands, without an LLM, and without sending your code anywhere.

by @voonterr

English · Русский

local-first · no API key · no LLM · CI-ready · safe static analysis

The problem

README files drift.

A command gets renamed. A file moves. .env.example disappears. The project switches from Yarn to npm. AI-generated documentation confidently describes a script that never existed.

Most Markdown linters can tell you whether the document is formatted correctly. RealityLint asks a different question:

Do the locally verifiable claims in this README still match the repository?

It stays deliberately conservative: if a claim cannot be proven from local repository evidence, RealityLint skips it instead of guessing.

30-second demo

realitylint examples/broken-project --fail-on never

RealityLint v0.1.3 — by @voonterr
RealityLint score: 34/100

✗ README.md:3 ERROR   RL002 Documented local link target "docs/setup.md" does not exist.
! README.md:6 WARNING RL004 README uses yarn, but the repository has only an npm lockfile.
✗ README.md:7 ERROR   RL001 Documented package script "dev" is not defined in package.json.
✗ README.md:8 ERROR   RL003 Documented environment template ".env.example" does not exist.
✗ README.md:9 ERROR   RL005 Documented Python entry file "scripts/start.py" does not exist.

4 error(s), 1 warning(s), 0 notice(s).

Why RealityLint?

What it checks

RealityLint also understands common cd subdir && ... flows, npm --prefix, yarn --cwd, pnpm --dir / pnpm -C, bun --cwd, make -C, nested README link bases, Windows-style path separators/prompts, backtick/tilde shell fences and inline shell commands.

Quick start

Requires Python 3.10+.

git clone https://github.com/voonterr/realitylint.git
cd realitylint
python -m pip install -e .
realitylint .

Or run it from the source checkout without installing the console script:

python -m realitylint /path/to/repository

Try the intentionally broken fixture:

realitylint examples/broken-project --fail-on never

GitHub Actions

Add this to .github/workflows/realitylint.yml in another repository:

name: README reality check
on: [pull_request]

permissions:
  contents: read

jobs:
  realitylint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: voonterr/realitylint@v1
        with:
          fail-on: error

The action emits inline annotations and a Markdown job summary.

Note: voonterr/realitylint@v1 becomes usable after the first v1 tag is published. See PUBLISH.md for the release checklist.

Output formats

realitylint . --format text
realitylint . --format json
realitylint . --format markdown
realitylint . --format sarif

CI failure policy:

realitylint . --fail-on error
realitylint . --fail-on warning
realitylint . --fail-on never

Machine-readable formats keep stdout clean — the by @voonterr banner does not corrupt JSON or SARIF output.

Security model

RealityLint is intentionally a static checker, not a sandbox.

• README commands are parsed, never executed.
• --readme cannot escape the repository root.
• Symlink/path resolution is contained before files are read.
• README and metadata files have size limits to reduce memory/regex abuse.
• GitHub Action inputs are passed through environment variables instead of direct shell interpolation.
• GitHub annotations escape workflow-command control characters.
• Third-party Actions used by this repository are pinned to immutable commit SHAs.
• No network access is required for the scanner itself.

Found a security issue? Please read SECURITY.md instead of opening a public exploit report.

Project philosophy

1. Evidence over vibes. Every finding should point to repository evidence.
2. No arbitrary execution. Documentation commands are parsed, never run.
3. Prefer silence to a false accusation. Ambiguous syntax is skipped.
4. Local-first. Source code and docs stay on the user's machine.
5. Small rules, easy contributions. Ecosystem checks should remain isolated and testable.

Roadmap

Near-term priorities:

• Go: go run, module path and toolchain claims
• Rust: cargo run --bin, features and MSRV claims
• Docker Compose service/port verification
• .env variable drift: code ↔ template ↔ docs
• pre-commit hook
• ignore directives for intentional examples
• CLI flag verification from generated --help snapshots

See the detailed ROADMAP.md.

Contributing

Bug reports, rule ideas and pull requests are welcome.

python -m unittest discover -s tests -v

Start with CONTRIBUTING.md. New contributors can also open a rule request using the repository issue template.

Status

RealityLint is currently alpha software. Its checks are intentionally narrow and deterministic. It will not understand every shell expression or every documentation style — and it should not pretend to.

Author

Created and maintained by @voonterr.

If RealityLint saves you from a broken README, consider ⭐ starring the repository — it helps other developers discover the project.

License

MIT License. Copyright © 2026 voonterr. See LICENSE.