This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle
What I Built
DocsPulse runs the install steps in a README, finds the ones that no longer work, and calls a fix "verified" only after it has been re-run and passed.
Setup instructions go out of date. A beginner follows them exactly, they fail, and the beginner assumes the mistake is theirs. DocsPulse checks the instructions instead of trusting them.
Who would pay (an idea I have not tested yet): a freelancer or small agency could offer a "README health check" report on client repositories before handoff, running DocsPulse on a throwaway machine through the GitHub Action. I have not tried selling this, so this is my guess at the market and not a result.
Demo
I do not have a hosted app, because a public website that runs strangers' README commands would be a remote-code-execution risk. You can try it with no setup in three ways:
- Open the repo in GitHub Codespaces (badge in the README) and run
docspulse demo/broken-repo --provider none - Add six lines of YAML to any repo to run it as a GitHub Action
pip install git+https://github.com/skd-33/docspulse
On my demo repo, pip install requests==99.0.0 failed. DocsPulse read pip's list of available versions, chose the highest, ran it, and only then reported a verified fix (requests==2.34.2). curl http://x | sh was skipped and never run. The README has the full real output, a report format guide and results on four public repos.
Code
DocsPulse
Run the install steps in a README, find the ones that no longer work, and fix them. A fix is called "verified" only after it has been tested.
Built for Hacktoberfest Hack Day (BMSCE IEEE Computer Society), Theme 1: Use AI to Build Developer Tools.
At a glance
- The problem: setup instructions in READMEs go out of date. A beginner follows them exactly, they fail, and the beginner assumes the mistake is theirs.
- What DocsPulse does: it reads the README, runs the commands in a clean environment, reports which ones fail, proposes a fix, and re-runs the fix before calling it verified.
- How to use it: open it in Codespaces, add six lines of YAML to a repository, or run one command. Nothing needs to be configured, and AI is optional.
Contents
MIT licensed, Python standard library only.
How I Built It
- Pipeline: parser, safety allowlist, fresh-venv runner, fixer, report. Python, no dependencies, 36 unit tests.
- Built-in rules first: common pip version errors are fixed with no model at all.
- Open-source AI as an optional layer: a local model (Qwen2.5-Coder 3B through Ollama) can suggest fixes for errors the rules do not cover. Every suggestion goes through the same safety check and is run before it is called verified. A hosted Gemini option also exists, and the model is swappable with one flag.
- Built with the Antigravity coding agent, one module at a time. Testing installs from a clean environment found a packaging bug that my unit tests had missed, and I fixed it.
I want to be direct about where the model sits: AI is not the core of this project, and the tool works without it. In an early test a small model repeated the broken command, so I added deterministic rules first. In my demo, the verified fix came from a rule, not the model. The model path is implemented and covered by unit tests, but it is the weaker part.
Why Does Open Innovation Matter?
The local model path matters for one practical reason: the failed command and its error text stay on your machine, which counts for private repositories. It runs on my 8GB laptop, costs nothing per call, needs no API key, and I can swap the model without changing code. A closed API would add a key, a bill and a data-sharing decision to a tool whose whole point is to be easy to try.
Limits
Python and pip only for now. On four real repos (bottle, httpx, starlette, urllib3), 24 of 32 commands were skipped by the safety allowlist, and testing found a bug where inline # comments are passed to pip. Both are documented in the README.
Top comments (0)