Test README code examples with readme-ci
README examples are copied by developers and AI agents, but they are rarely executed by the project that publishes them. readme-ci turns safe examples into continuous-integration checks.
The documentation gap
A test suite can remain green while the installation command, API example, or configuration snippet in the README has stopped working. As agents consume documentation at scale, one stale example can be copied into many repositories before a person reports it.
readme-ci extracts fenced code examples from Markdown, classifies whether they can be run safely, and executes eligible examples in a locked-down container with no network access.
What it provides
- Markdown example extraction
- Runnable-example classification
- Network-isolated execution
- CI-friendly pass and failure results
Why sandboxing matters
- Documentation is untrusted input.
- Not every code block is intended to run.
- Examples should not reach external services.
- Failure should be reproducible locally.
Use it
Install with pip install readme-ci. Start with one repository and review which examples are classified as runnable before adding it as a required CI check.
Current adoption priority
The roadmap prioritizes demonstrated execution against live repositories over adding more surface area. Reports of false positives, unsafe classifications, unsupported Markdown patterns, or confusing output are product evidence—not incidental feedback.