Sub Engel

Posted on Oct 30

ghostwalk: an ofrenda for the forgotten files in your git repo

#devchallenge #hf26challenge

Hacktoberfest Open-Source AI Challenge: Ghost in the Machine Submission 👻🌼

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

What I Built

Every old repo has ghosts. Files nobody has opened in years. Branches someone started and walked away from. TODO and FIXME notes from people who left the team long ago.

ghostwalk is a small Python CLI that finds them. It walks a git repo and lists:

files nobody has touched in N days
abandoned branches
TODO/FIXME notes, with who left them (via git blame)

Then a small open-weight model running on your own CPU writes a one-line, Día de los Muertos style epitaph for each ghost. You can save the whole thing as ofrenda.md, a little altar for the code your team left behind.

I took the theme literally: honor the past of a codebase, and the people whose names are still in its history.

Demo

A real terminal recording (about 23 s): python ghostwalk.py records --days 365 --max 6 --out ofrenda.md finds 6 file ghosts, the local Qwen model writes their epitaphs in 2.9 s on CPU, and it saves ofrenda.md. Like the run below, the demo only shows file ghosts; the branch and TODO detectors are covered by tests.

Here's a real run on the public repo kennethreitz/records, on an 8-core CPU:

🕯  ghostwalk: 6 ghosts found in /tmp/records

👻 [file] .gitignore (untouched 4214 days, last by Kenneth Reitz)
   🌼 .gitignore, untouched 4214 days, last by Kenneth Reitz.
👻 [file] MANIFEST.in (untouched 3918 days, last by Kenneth Reitz)
   🌼 The file remains untouched 3918 days, a testament to its preservation.
👻 [file] tests/__init__.py (untouched 3914 days, last by Harold Cooper)
   🌼 `Unwritten Code: The Untouched File of Harold Cooper, 3914 days old.`
👻 [file] LICENSE (untouched 3348 days, last by Waldir Pimenta)
   🌼 `LICENSE` remains unchanged since Waldir Pimenta's last use, a reminder of forgotten knowledge.
👻 [file] tests/test_records.py (untouched 3179 days, last by Joakim Uddholm)
   🌼 This file is no longer needed, but Joakim Uddholm's touch made it worth remembering.
👻 [file] .travis.yml (untouched 3121 days, last by Jan Vlcinsky)
   🌼 Untouched, untouched, it remains.

Epitaphs written in 2.8s on CPU. No cloud, no API key, $0.
Ofrenda saved to /tmp/ofrenda.md

That run only turned up file ghosts. The branch and TODO detectors didn't find anything there, but each one has its own unit test (test_abandoned_branch and test_orphan_todo_blamed, which also checks the TODO gets blamed on the right author).

I'm leaving that output as-is, including the weak epitaphs. More on that below.

Code

https://gitlab.com/engelstands-hue/ghostwalk

MIT licensed. 5 tests pass in CI: latest test job.

To try it:

pip install -r requirements.txt --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
curl -L -o models/qwen2.5-0.5b-instruct-q4_k_m.gguf https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf
python ghostwalk.py path/to/repo --days 365 --out ofrenda.md

--days defaults to 180; I used 365 above. Other flags:

--no-ai lists the ghosts without running the model
--max caps how many ghosts you get (default 12)
--out ofrenda.md saves the ofrenda
--model <path to .gguf> swaps the model (default is the Qwen2.5-0.5B-Instruct Q4 GGUF above)

How I Built It

Model: Qwen2.5-0.5B-Instruct (Apache-2.0), as a Q4_K_M GGUF file, about 490 MB.
Inference: llama.cpp through llama-cpp-python 0.3.36, on CPU. No GPU needed.
Everything else: plain git. Last-touched dates come from git history, abandoned branches from the branch list, and TODO/FIXME authors from git blame.

The git part finds the facts. The model only gets one job: turn each fact into a short epitaph. After the one-time model download, it needs no API key and no network.

Honest limits: the 0.5B model is fast, but it sometimes just restates the facts instead of writing something nice. "Untouched, untouched, it remains." is a real example. A bigger GGUF writes better epitaphs, just more slowly. Since it's an open model, swapping one in is one flag:

python ghostwalk.py path/to/repo --model models/your-bigger-model.gguf

Why Does Open Innovation Matter?

A repo's history is a team's private memory: who left, and what they never finished. That's not something I'd want to ship off to a cloud API just to get a joke epitaph.

Because ghostwalk runs an open-weight model locally:

the history never leaves your machine
it works offline
each run costs nothing
you're not stuck with my model choice. Since the model is open, you can point --model at a bigger or fine-tuned one

A closed API would have meant sending names and commit history to someone else's server, needing a key, and paying per run, for a tool whose whole point is a little Halloween fun with your own repo.

The Spirit of It

What got me wasn't the epitaphs, it was the names. Real people wrote those files years ago, and the repo still remembers them. ghostwalk just lights a candle for them.

License: MIT. Built by Engel AI Labs.

DEV Community