This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine
NecroGit: A Little SĂ©ance for Legacy Code
Every codebase has a past.
Sometimes that past is a beautifully maintained changelog. Sometimes it is a function named do_not_delete_final2(), three deprecated imports, and a Git history that only the person who wrote it really understood.
Then that person leaves.
The code stays.
For Week 4's Ghost in the Machine challenge, I built NecroGit: a command-line tool that treats legacy-code maintenance like a bit of software archaeology. It looks for signs of bitrot, examines Git history for clues about how a project evolved, and uses an open-weight language model to help explain unfamiliar code and propose repairs.
The goal isn't to pretend a model can bring a developer back from the dead. It's to make the traces they left behind more useful to the next person who has to maintain the project.
What I Built
NecroGit is a Python CLI for developers inheriting repositories they didn't write.
It brings a few kinds of investigation into one workflow:
- Inspect: scan Python files for known deprecated APIs and suspicious legacy patterns.
- Summon: examine Git commits and author activity for historical context.
- Explain: ask a language model to explain an unfamiliar function using the source and available repository context.
- Patch: generate a proposed diff that a developer can review before applying.
- Memory: keep a small repository dossier so useful context can carry between sessions.
The part I care about most is the connection between these steps. Finding a deprecated import is useful. Understanding why the surrounding code exists is better. Getting a proposed change that you can inspect, test, and reject if necessary is better still.
NecroGit is meant to assist the maintainer, not replace their judgment. Git history can offer clues about a previous developer's habits; it cannot tell us with certainty what that person intended. Likewise, an AI-generated patch is a proposal, not proof that the fix is correct.
Demo
Repository: github.com/avrojitduttaj/necrogit
The quickest way to see the workflow is to install the project in a Python environment, open a repository in your terminal, and try the inspection command:
necrogit inspect .
Then explore the other commands with:
necrogit --help
necrogit summon .
necrogit memory
The exact arguments for explain and patch depend on the installed CLI version; check each command's --help before running it.
Live demo / walkthrough: [Add a verified demo URL or video here]
I don't want to pass off a mockup as a working demo, so this post links to the source repository. If I add a hosted walkthrough, I'll put the verified URL here.
Code
The source is available here:
Live Deployment: NecroGit — The Repository Medium
A few of the implementation choices:
- Python's
astmodule provides a structured way to inspect source code without executing it. - GitPython reads repository history and commit metadata.
- Click provides the command-line interface, with Rich for readable terminal output.
- HTTPX connects the engine to an OpenAI-compatible local model endpoint.
- Repository dossiers can be stored locally, with optional Backboard integration in the project.
The intent is to keep the first step—static inspection—useful even when an AI model isn't available. The AI-assisted commands should fail clearly when inference isn't configured, rather than pretending they succeeded.
How I Built It
I built NecroGit around a simple question: what if Git history were more than a list of commits?
The scanner handles the deterministic part. It parses Python syntax and checks for patterns the tool knows about. The Git-history component gathers evidence such as authorship, commit dates, and commit messages. The AI engine can then use the available code and context to generate an explanation or a proposed diff.
For the open-model path, NecroGit is designed to work with Gemma 2 through Ollama, using a local OpenAI-compatible endpoint. That makes it possible to experiment with the model on your own machine rather than making a hosted, closed API the only way to run the project.
This separation matters:
- Rules find known patterns. They are predictable, testable, and don't need a model.
- Git history supplies evidence. It gives context, but it isn't a source of certainty about intent.
- The model helps interpret and draft. It can explain code and suggest changes, but its output still needs review and tests.
During development, I also added tests for deprecated-import detection, Git and non-Git directories, prompt construction, connection failures, local memory persistence, and CLI behavior. Those tests have been useful for catching mismatches between the intended user experience and what the command actually does.
One lesson from building a CLI is that a feature isn't finished just because the Python function works. Packaging, command registration, Windows paths, model endpoints, and readable error messages are all part of the product. I'm still tightening those edges, and I want to be honest about that rather than call the tool production-ready before it earns the label.
Why Does Open Innovation Matter?
For a tool that reads source code, where inference happens is part of the design.
A developer may be working with a private repository, a client's code, or an abandoned internal service. Sending that code to an external API should never be an invisible default. A local model gives the developer a path to keep inference on their own machine, subject to how they've configured the rest of their environment.
Open-weight models also make the system more replaceable. Developers can experiment with different models and local runtimes instead of tying the whole experience to one provider's API, pricing, or product decisions.
And the non-AI parts remain ordinary, inspectable software. The scanner's rules can be read and tested. The Git-history analysis can be audited. A proposed patch is visible as a diff.
That doesn't mean every setup is automatically offline or private: optional integrations and telemetry need to be configured and disclosed carefully. But open tooling gives developers more control over those trade-offs—and for a maintenance tool that may touch sensitive code, that control is important.
My Agent Session
[https://dev.to/agent_sessions/finding-the-necrogit-devrelay-session-link-xmpym5]
This section is optional. I will only link a real saved session; I won't invent an embed or session URL.
The Spirit of It
There's something eerie about opening a repository and finding a whole history of decisions with nobody left to explain them.
A commit message says “temporary workaround.” The workaround is still there six years later. A function has a strange name because it once fixed a production incident. A dependency is obsolete, but nobody remembers which behavior relied on it.
The ghost isn't really the old developer. It's the missing context.
NecroGit is my attempt to make that context a little easier to recover—from the code, from the commit history, and from the tools we can run ourselves. Not to resurrect the past exactly as it was, but to help the next maintainer move forward without blindly deleting it.
🏆 Prize Categories I'm Targeting
[ ] Overall Challenge Winner — $250
NecroGit aims to make legacy-code maintenance easier by combining Git-history archaeology, AI-assisted code explanations, and safer patch proposals.[ ] Best Use of Gemma — $200
Gemma 2 powers NecroGit's local AI inference workflow, helping explain historical design decisions and draft modernization patches while keeping source code on the developer's machine.[ ] Best Use of Backboard — $100
NecroGit implements persistent repository dossiers, with local JSON storage and an optional Backboard synchronization path for retaining maintainer context across sessions.[ ] Best Use of Sentry Agent Tracing — $100
NecroGit includes instrumentation for tracing AI inference and memory operations, with breadcrumbs and structured context to help diagnose the resurrection workflow.
Deployment
NecroGit's web workbench is deployed on Render to make the project website accessible online. Render is used as a hosting and deployment platform, not as an AI integration.
The core NecroGit CLI remains a local developer tool, while the hosted website serves as the public-facing project experience.
Built by @avrojitduttaj.
If you've inherited a codebase that feels haunted, I'd love to know: what's the strangest piece of legacy code you've had to explain?
Top comments (0)