Ghost in the Repo: Resurrecting Abandoned Code with a Local Open Model

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

README Resurrection is a command-line tool that raises abandoned repositories from the dead. Point it at a repo with no documentation and it writes a README, setup instructions, an architecture overview and a contributing guide, using a local open-weight model. Then it checks its own work and flags anything it couldn't verify.

For the theme, I took "ghost in the machine" literally. An abandoned project is a ghost: the code is still there and still runs, but the person who understood it is gone. Documentation is how the living remember the dead, so I wanted a tool that goes through a forgotten repo and writes down what it was. Before it generates anything, it prints a "Resurrection report" that says whether the repo is alive, dormant or dead, and how much documentation it's missing.

Code

AbbeyIT / readme-resurrection

A tool for generating README.md files for software repositories using various facts about the repository.

How I Built It

The open stack: Ollama running Qwen2.5-coder:7b locally, with a small Python CLI (typer, rich, httpx) around it. There are no API keys and no hosted models in the product. I developed it on a Windows laptop with no GPU, so the model runs 100% on CPU.

The lesson that shaped the design: a small model asked to "write a README" invents things. My first generated README had a Usage section with command-line arguments that don't exist. Its Architecture document claimed modules imported each other when they didn't. The model wasn't broken; my facts had gaps, and it filled them with plausible guesses.

So the tool does as little as possible with the model:

1. Plain code collects the facts: file tree, languages, dependencies, entry points, scripts, license type (detected from the license text), and the real Python import graph read with the ast module.
2. The model summarizes key files, with results cached by content hash.
3. The model writes each document from those facts only, with a list of verified commands it's allowed to use and a rule to write unknown rather than guess.
4. Plain code verifies the output. Every file path, command and "X imports Y" claim is checked against the repo, and anything that doesn't hold up goes into a ## Needs review section.

Each time a document was wrong, the fix was never a cleverer prompt. It was a better fact, extracted by code: the CLI entry point from pyproject.toml, the license type from the license text, the optional [dev] dependencies, the import graph.

How the code got written:
I tried driving the build with opencode pointed at a local Ollama model, but on CPU it ran at about 0.3 tokens per second and the 7B model printed its tool call as plain text instead of executing it, so no files were created. I then built the project in small steps with a hosted AI assistant helping draft the code, and I ran, tested and committed each step myself.

Why Does Open Innovation Matter?

The people who most need this tool are working with code they can't upload. Legacy and proprietary repositories are exactly where documentation is missing, and exactly where sending the source to a closed API isn't an option. With an open-weight model running through Ollama:

• The code never leaves the machine. That's the difference between a tool you could use at work and one you couldn't.
• It works offline. Once the model is pulled, no network is needed (except to clone a repo).
• The model is swappable. --model takes any Ollama model, and all model access is in one small file. When I found my 7B model was slow on CPU, switching to a smaller one was a flag, not a rewrite.
• It costs nothing to run. No keys, no per-token billing, so it's practical to re-run it on a whole folder of old repos.
• Nothing is locked in. There's no service that can change pricing, retire a model, or disappear. That seemed right for a tool whose whole point is rescuing things that were abandoned.

Open models also made the hard part easier to see. Because I could run the same small model locally and watch exactly where it went wrong, I learned that the answer was grounding it in facts, and the same approach would help with larger models too.

The Spirit of It

I pointed the tool at GitHub's oldest demo repository, octocat/Hello-World, to see how it describes a ghost:

Condition      DEAD - last commit 2012-03-06, 14 years, 8 months (5,351 days) ago
README         stub (README, under 500 bytes)
SETUP          missing
ARCHITECTURE   missing
CONTRIBUTING   missing
Revival score  100/100  ##########

This is from my own repo: