GitGhost：鬧鬼程式碼考古師與遺留技術債驅魔工具

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

What I Built

Every software engineer has inherited a codebase haunted by the departed.

You open an unfamiliar file and discover an arcane block of logic paired with a terrifying comment:
// DO NOT TOUCH THIS. ONLY GOD AND BOB KNOW WHY THIS WORKS.
You check git blame: Bob left the company in 2019.

You find tombstone comments like // TODO (2018): Refactor this before next sprint. You stumble across frantic late-night commits: wip emergency fix, please work god. When you try to touch or modernize this code, unforeseen production outages strike. The original architects are gone, documentation is lost, and the software behaves like an unpredictable, possessing presence.

GitGhost brings these invisible spirits to life.

GitGhost is a local-first open-source developer agent that turns code archaeology into an interactive séance. It excavates your .git history, blame trees, and ancient comments, and channels the "ghosts of past contributors" through local open-weight AI (like Google Gemma 2 or Qwen 2.5-Coder).

Key Features:

1. 🕯️ The Haunt Scanner & Haunt Meter: Calculates your repository's Haunt Score (0–100%) by detecting ancient unresolved tombstones (TODO, FIXME, HACK, MAGIC, BUG), desperate midnight commits, zombie commented-out blocks, and the oldest surviving line in your tree.
2. 🔮 The Séance Chamber: Select any ancient relic or tombstone. GitGhost synthesizes historical git metadata and summons the spirit of the past author to explain why the hack was written, what crisis they were fighting, and what catastrophic edge-case will break if you delete it.
3. ✨ The Exorcism Protocol: GitGhost doesn't just complain—it banishes technical debt by generating a clean modernized refactoring patch (.diff) and synthesizing an automated regression verification test suite.

Demo

GitGhost provides both an atmospheric, high-contrast terminal CLI (with ASCII ghost art and audio-visual text effects) and a sleek, glowing dark-mode Web Portal.

1. The Haunt Meter & The Crypt of Tech Debt

Scanning an active repository to uncover ancient tombstones, possession levels, and lingering developer phantoms.

2. The Séance Chamber: Channeling Past Contributors

Summoning the ghost of a past engineer to question why an emergency hack was written, followed by the Exorcism Protocol generating clean refactoring diffs.

3. Terminal CLI in Action

$ python -m gitghost.cli scan

          .---.
         /     \      G I T G H O S T
        | () () |     The Haunted Code Archaeologist
         \  ^  /      Open-Source AI for Hacktoberfest '26
          |||||       Theme: Ghost in the Machine 👻
          |||||

🔍 Commencing Archaeological Excavation on: C:\repos\project

╭─────────────────────── 🎃 Repository Haunt Diagnosis ────────────────────────╮
│ Repository: openlibrary                                                      │
│ Haunt Score: 78% (CRITICALLY POSSESSED 💀)                                   │
│ Files Scanned: 142 | Lines of Code: 48,920                                   │
│ Tombstones Uncovered (TODO/FIXME/HACK): 34                                   │
│ Cryptic Commits Detected: 12                                                 │
│ Zombie Commented Blocks: 7                                                   │
╰──────────────────────────────────────────────────────────────────────────────╯

Code

The complete source code for GitGhost is 100% open-source under the MIT License:

🔗 GitHub Repository: https://github.com/n1t1n-cyber/gitghost

• Built with: Python 3.11, Rich, FastAPI, Uvicorn, Vanilla CSS Glassmorphism, and Open-Weight AI (Ollama Gemma 2 / Qwen 2.5 + offline Spectral Synthesizer).

How I Built It

GitGhost is architected around local-first speed, historical accuracy, and atmospheric immersion:

   ┌─────────────────────────────────────────────────────────────┐
   │                   Git Repository (.git)                     │
   └─────────────┬─────────────────────────────────┬─────────────┘
                 │ (git blame, log, ast)           │
                 ▼                                 ▼
   ┌───────────────────────────┐     ┌───────────────────────────┐
   │    Archaeology Engine     │     │      Tombstone Parser     │
   │    (scanner.py)           │     │ (TODOs, HACKs, Blame Tree)│
   └─────────────┬─────────────┘     └─────────────┬─────────────┘
                 │                                 │
                 └───────────────┬─────────────────┘
                                 ▼
   ┌─────────────────────────────────────────────────────────────┐
   │        Ghost Context Synthesizer (Historical Prompt)        │
   └─────────────────────────────┬───────────────────────────────┘
                                 ▼
   ┌─────────────────────────────────────────────────────────────┐
   │           OPEN-WEIGHT MODEL INFERENCE (100% LOCAL)          │
   │       Ollama (Gemma 2 / Qwen 2.5) | Air-Gapped Engine       │
   └─────────────────────────────┬───────────────────────────────┘
                                 │
                 ┌───────────────┴───────────────┐
                 ▼                               ▼
   ┌───────────────────────────┐   ┌───────────────────────────┐
   │     Rich Terminal CLI     │   │    Sleek Web Dashboard    │
   │      (python -m cli)      │   │  (Obsidian & Ectoplasm)   │
   └───────────────────────────┘   └───────────────────────────┘

1. The Archaeology Engine (scanner.py): Traverses the repository using git blame -L --porcelain and git log to map each comment, hack, and function to its original author, commit date, and commit message.
2. The Open-Source AI Core (ghost_ai.py): Connects to local Ollama running open-weight models (Google Gemma 2 or Qwen 2.5-Coder). The prompt grounds the model in historical facts—the exact timestamp, commit message, author name, and diff context—instructing it to adopt the eerie, weary, yet technically sharp persona of that past engineer.
3. Air-Gapped Spectral Fallback: To ensure zero friction for anyone testing without an active GPU or Ollama daemon, GitGhost features an offline deterministic heuristic synthesizer that preserves the full experience without network requests.
4. The Exorcist Engine (exorcist.py): Analyzes the legacy anti-pattern, extracts the implicit safety contract, and synthesizes a modern, typed, null-safe replacement diff along with automated regression tests.
5. Modern Frontend & CLI (web/ & cli.py): Built with Vanilla CSS, glassmorphism, animated mist particles, and custom radial progress gauges, alongside a Rich CLI terminal.

Why Does Open Innovation Matter?

This challenge asks: Why does open innovation matter for your build?

For developer tooling and code archaeology, open innovation is not just a preference—it is a non-negotiable security requirement.

1. Enterprise Privacy & IP Protection

Proprietary corporate codebases contain trade secrets, patentable algorithms, and confidential business logic. No enterprise engineering team can legally or responsibly stream their raw source code and historical commit logs across the internet to closed third-party cloud APIs (such as OpenAI or Anthropic).

By utilizing open-weight models (Gemma 2, Qwen 2.5) running locally via open runtimes:

• Zero Cloud Leakage: Sensitive code, author names, and corporate git logs never leave the developer's laptop.
• Air-Gapped Security: GitGhost functions entirely offline, inside secure VPCs, on air-gapped defense networks, or on an airplane with no internet.

2. Guarding Against Vendor Lock-in & Arbitrary Deprecation

Closed cloud LLMs constantly change models, alter safety alignments, and deprecate endpoints. Open-weight models belong to the community: they can be audited, quantized, fine-tuned on company-specific idioms, and archived forever.

Open innovation ensures that the developer—not a cloud API billing meter—owns the intelligence in their machine.

My Agent Session

GitGhost was conceptualized, built, tested, and polished in an intensive pair-programming session with an AI coding partner in Google Antigravity. We collaborated to design the archaeological git blame parsing engine, optimize Windows terminal UTF-8 encoding for Rich markup, construct the responsive Halloween glassmorphism UI, and execute automated browser testing to verify the séance interaction flows.

Happy Halloween & Happy Hacktoberfest! May your code be forever exorcised of legacy bugs. 🎃👻