This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine
What I Built
Every abandoned repository has a ghost: forgotten intentions, mystery functions, orphaned TODO comments, and undocumented architectures whose original creators have long since moved on.
I built DeadCode — The Ghost of Forgotten Code, a spooky, privacy-first AI code archaeology tool that helps developers explore, diagnose, and revive forgotten software repositories.
Instead of running untrusted code or sending private source files to third-party cloud APIs, DeadCode acts as a digital ghost residing locally inside the repository:
- Performs deterministic static analysis: Parses Python Abstract Syntax Trees (AST), finds empty function stubs, unearths
TODO/FIXME/HACKmarkers, audits unpinned dependencies, and checks for dangerous anti-patterns (eval,subprocess shell=True, unsafepickle.loads). - Calculates a Repository Health Heuristic: Provides an honest 0–100 estimate of code dormancy and technical debt.
- Interrogates the Ghost: Uses a locally running, quantized open-weight model via Ollama to explain unfamiliar functions, decipher architectures, and suggest contribution starting points—with line-numbered citations.
- Writes "The Last Will of This Repository": Generates a comprehensive architectural summary and a phased revival roadmap (First Hour, First Day, First Week) downloadable as Markdown (
.md) and JSON (.json).
Tagline: “Every repository has a past. Let AI uncover its unfinished story.”
Demo
DeadCode features a dark Haunted Terminal interface built with Streamlit, styled with glowing cyan, eerie green, and muted violet accents, accompanied by a custom CSS ghost mascot.
Key Capabilities in Action:
- Instant Ingestion: Point to any local folder path or upload a
.ziparchive. - Built-in Demo Repository: One-click loading of
phantom_vault(a realistic legacy Python service from 2021 with stubs, security anti-patterns, and unpinned dependencies). - Interactive Ghost Q&A: Grounded answers backed by line-numbered excerpts and strict secret redaction.
- Graceful Offline Mode: Runs in 100% deterministic mode even when Ollama is offline or not installed, clearly labeling deterministic facts from AI estimates.
Code
The project is fully open source under the MIT License.
