Phantom.exe

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

#

What I Built

I built PHANTOM.exe — The Ghost in Your Codebase, a local-first, open-source AI coding companion and static repository forensics tool with an atmospheric Cyberpunk CRT terminal persona.

The central premise behind PHANTOM.exe:

"What if your abandoned codebase had a ghost that remembered everything?"

Every developer has a graveyard of side projects, legacy microservices, or half-finished feature branches where context has been lost to time. Instead of acting like a generic cloud-hosted chatbot that requires up private source code to external servers, PHANTOM.exe inhabits your local project directory like a sentient digital entity that remembers every unfinished function, every forgotten TODO/ FIXME, every broken syntax tree, and every dormant file in your Git history.

Core Capabilities

🔦 Haunted Codebase Scanner: Static, read-only repository forensics using Python'sast module and multi-language heuristics (across 35+ extensions). It detectspass stubs,... (Ellipsis) placeholders, functions raisingNotImplementedError , empty classes, mutable default arguments, bareexcept: clauses, confirmedSyntaxError s,TODO /FIXME /HACK /BUG markers, and orphan backup files—computing aCodebase Health Score (0–100) andHaunt Level without ever importing or executing target repository code. 2. 👻 The Ghost AI (Local Ollama Inference): Powered by open-weight language models running locally viaOllama (qwen2.5:3b by default, configurable toqwen2.5-coder:7b ,llama3.2:3b ,mistral , etc.). PHANTOM speaks in a calm, eerie, observant, and developer-focused persona grounded strictly in actual repository telemetry so it never fabricates file names, commits, or bug counts. If Ollama is offline, PHANTOM degrades gracefully to a deterministicEcho Fallback Mode while keeping all static analysis features 100% operational. 3. 🕯️ Digital Memories (Git Forensics): Dual-engine Git history analyzer (GitPython + nativegit CLI fallback) that extracts commit timelines, active branch (DETACHED_HEAD and shallow-clone aware), contributor breakdowns, frequently modified hotspot files, and dormant files, while strictly separatingVerified Git Facts (Objective) fromPHANTOM's Memory Whispers (AI Persona) . 4. 🧪 Paranormal Debugger: Unified static diagnostic inspector categorized by severity (critical ,high ,medium ,low ) and confidence level (confirmed AST parser ,AST analysis ,heuristic indicator ,developer annotation ), with one-click**"Summon PHANTOM to Explain"** root-cause analysis and remediation advice. 5. 📜 Last Words Report Generator: Generates a complete post-mortem and revival blueprint—synthesizing inferred project purpose, completed work, unfinished work, hotspot files, last Git pulse, recommended revival steps, and a closing statement from PHANTOM—exportable with one click as a standalone Markdown (.md ) report. 6. 🔒 Enforced Local-First Privacy Vault: Enforces a loopback-only Ollama boundary (localhost ,127.0.0.1 ,::1 ) by default across the UI, saved settings, and API endpoints (requiring explicit opt-in with a clear warning for remote hosts), excludes sensitive files (.env ,*.pem ,id_rsa ,credentials.json ), and applies conservative secret redaction across code snippets,TODO comments,README summaries, and Git commit messages.

#

Demo

Sample Ghost Transmission (SpecterAuth Abandoned Repository)

Interactive 7-View Cyberpunk CRT Dashboard (http://localhost:8501)

1. Overview: Cyberpunk CRT hero header with live telemetry pills (AI LINK ,OLLAMA ,MODEL ,REPO ,PRIVACY: LOOPBACK ONLY ), live Ghost Terminal transmission, 6 metric cards, Quick Séance prompt bar, language distribution bars, and top hotspot files. #

2. Haunted Scanner: Partial-scan boundary telemetry, unfinished AST function tables,TODO /FIXME explorer, attention-ranked files, protected sensitive file inventory, and non-fatal scan error logs. #

3. Ghost Chat: Streaming neural séance terminal with one-click preset prompts ("What happened here?" ,"Unfinished functions" ,"Security & Bugs" ,"Explain TODOs" ). #

4. Digital Memories: Side-by-side Verified Git Facts vs. PHANTOM Memory Whispers, commit activity chart, hotspot/dormant file tables, and commit timeline. #

5. Paranormal Debugger: Severity/category filters and per-finding AI explanations. #

6. Last Words: Post-mortem revival report with raw Markdown preview and.md download. #

7. Settings & Privacy Vault: Ollama host/model selector, explicit remote-host opt-in guard, connection tester, installed models table, and one-click SQLite data purge controls.

#

Code

Quick Start

#

How I Built It

Architecture

Both the Streamlit Cyberpunk CRT Frontend (frontend/dashboard.py) and the FastAPI REST Backend ( app/api/routes.py) share a single unified service layer, PhantomService ( app/core/service.py), ensuring consistent host policy validation, exact model tag resolution, static scanning, secret redaction, and SQLite persistence across the entire application.

flowchart LR
    subgraph UI["Streamlit Dashboard (frontend/dashboard.py)"]
        ST_UI["7 Interactive CRT Terminal Views"]
    end

    subgraph API["FastAPI Server (app/api/routes.py)"]
        REST["REST Endpoints (/api/*)"]
    end

    subgraph SVC["Unified Service Layer (app/core/service.py)"]
        PS["PhantomService"]
        SCN["HauntedScanner (Python AST + Heuristics)"]
        GIT["GitAnalyzer (GitPython + Git CLI)"]
        DBG["ParanormalDebugger"]
        RPT["LastWordsGenerator"]
        CTX["RepositoryContextBuilder + redact_secrets()"]
    end

    subgraph LOCAL["100% Local Persistence & Inference"]
        DB[("SQLite (data/phantom.db)")]
        OL[["Ollama Local Server (qwen2.5:3b)"]]
        FS[("Target Local Repository (Read-Only)")]
    end

    ST_UI --> PS
    REST --> PS
    PS --> SCN
    PS --> GIT
    PS --> DBG
    PS --> RPT
    PS --> CTX
    SCN --> FS
    GIT --> FS
    CTX --> OL
    PS <--> DB

Technology Stack & Key Engineering Decisions

Python 3.11+ & ast.NodeVisitor: Built PythonASTInspector to parse Python syntax trees safely in memory without ever importing or executing repository code, catchingpass and... stubs,NotImplementedError branches, empty classes, mutable default arguments (def fn(cache=[]) ), bareexcept: blocks, and exact line/columnSyntaxError s. #

Ollama + qwen2.5:3b Open-Weight Inference: ImplementedOllamaClient overhttpx with both synchronous and streaming (SSE / generator) chat, exact model tag verification (resolve_installed_model ), and deterministic fallback synthesis so the app remains useful even in air-gapped environments or before Ollama is started. #

Defense-in-Depth Privacy & Security Hardening: - Enforced path containment (is_safe_subpath ) and symlink skipping so scans cannot escape the target repository root.

• Enforced loopback-only Ollama URL validation (validate_ollama_host ) by default across all UI and API entrypoints.
• Excluded credential files (.env ,*.pem ,id_rsa ,credentials.json ) and redacted common token formats (PEM blocks, connection URIs with passwords, JWTs, AWS/GitHub/OpenAI/Stripe/Slack/Google keys, and quoted/unquoted secret assignments) across code snippets,TODO s,README summaries, and Git commit messages.

GitPython + Unit-Separated Git CLI Fallback: BuiltGitAnalyzer to inspect local.git repositories without walking into parent directories (search_parent_directories=False ), using ASCII unit separators (\x1f ) ingit log so pipe characters (| ) in commit messages never corrupt history parsing. #

Streamlit + Custom Cyberpunk CRT CSS + FastAPI + SQLite: Styled the 7-section interface with a custom dark obsidian and neon phosphor green CRT stylesheet (frontend/styles/main.css ) backed by lazy-initialized SQLite persistence (app/database/db.py ).

#

Why Does Open Innovation Matter?

Developer productivity and code intelligence tools should not require surrendering your source code, proprietary business logic, or unpublished Git commit history to closed, proprietary cloud APIs.

Open-source and open-weight AI models (such as Qwen 2.5, Llama 3.2, and Mistral) combined with local inference engines like Ollama make a fundamentally different software paradigm possible:

True Code Sovereignty & Privacy: When debugging a stalled repository or auditing legacy code for security issues and forgottenFIXME s, developers often work with sensitive codebases that cannot legally or safely leave their machine. Running open-weight models onlocalhost keeps every AST snippet and commit message inside the developer's own hardware boundary. 2. Zero API Keys, Zero Quotas, Zero Vendor Lock-In: Anyone can clonePHANTOM.exe , pullqwen2.5:3b (or swap in any other Ollama-compatible model in Settings), and run unlimited repository scans and debugging sessions offline without a credit card or recurring subscription. 3. Inspectable & Auditable Trust: When an AI tool claims to be "local-first" and "privacy-preserving," open source lets developers inspect the exact URL validator (validate_ollama_host ), path containment guard (is_safe_subpath ), and secret redaction rules (redact_secrets ) rather than trusting a black-box binary.

#

My Agent Session

I pair-programmed with Antigravity across an iterative architecture, implementation, security review, and verification workflow:

Architecture & Core Engine Design: We designed a modular Python package separating static forensics (HauntedScanner ,GitAnalyzer ,ParanormalDebugger ,LastWordsGenerator ), local AI inference (OllamaClient ,RepositoryContextBuilder ,PHANTOM_SYSTEM_PROMPT ), persistence (PhantomDatabase ), and presentation (frontend/dashboard.py +app/api/routes.py ). 2. Sample Haunted Codebase Creation: To makePHANTOM.exe immediately testable out of the box, we built a realistic abandoned microservice fixture (SpecterAuth indata/sample_abandoned_auth_service ) containing unfinished MFA/token-rotation functions, a mid-editSyntaxError , mutable default arguments,eval() /pickle /shell=True patterns, and multi-commit Git history. 3. Security, Privacy & Reliability Hardening Pass: Next, we conducted a rigorous application security and reliability audit: - Replaced duplicated UI/API scan and chat flows with a unified PhantomService layer (app/core/service.py ).

• Added strict loopback host validation (validate_ollama_host ) with explicit remote opt-in warnings so query/request overrides cannot silently exfiltrate repository context.
• Tightened model readiness checks (resolve_installed_model ) soqwen2.5:3b never falsely matchesqwen2.5:7b , and added structured handling for timeouts, malformed JSON, and mid-stream disconnects.
• Expanded secret redaction to cover unquoted assignments, connection strings, and Git commit messages, and added unit-separator (\x1f ) Git log parsing, symlink skipping, and partial-scan telemetry (scan_is_partial ,scan_errors ,oversized_files ).

Automated Verification: We wrote a 9-part pytest suite (tests/test_phantom.py ) testing host boundary enforcement, model tag matching, mocked Ollama failure modes and stream interruptions, multi-source secret redaction, symlink/path containment, scan limits, Git edge cases (empty repos, detachedHEAD , shallow clones, truncated history), and FastAPI HTTP endpoints viahttpx.AsyncClient +ASGITransport .

#

The Spirit of It

PHANTOM.exe embraces the "Ghost in the Machine" theme both aesthetically and functionally:

• Rather than treating an old or unfinished project like a sterile linter report, PHANTOM.exe turns repository archaeology into an atmosphericneural séance inside a retro Cyberpunk CRT terminal (#080B0D obsidian background,#39FF88 phosphor green glow, scanline overlays, and live terminal whispers).
• Every feature balances theatrical personality with strict engineering honesty: Digital Memories placesVerified Git Facts side-by-side withPHANTOM's Memory Whispers ,Paranormal Debugger distinguishes confirmed AST syntax errors from static heuristic indicators, and theLast Words generator transforms a haunted codebase's unfinished functions and lingeringTODO s into a concrete step-by-step revival plan.

#

Prize Categories

Open-Source Champion: Built entirely on open-source tooling (Python, FastAPI, Streamlit, GitPython, SQLite) and local open-weight AI models viaOllama (qwen2.5:3b ), with zero proprietary cloud API dependencies and an enforced local loopback boundary. #

Ghost in the Machine (Theme / Creativity): Embodies the literal ghost living inside your abandoned repository—remembering your last commit, cataloging your unfinished functions, and channeling a post-mortem*"Last Words"* revival blueprint through a Cyberpunk CRT terminal. #

Best Technical Execution & Security: Combines safe in-memory Python AST analysis, dual-engine Git forensics, defense-in-depth secret redaction across code and commit history, unified service architecture, graceful offline fallback, and a full automated test suite.

source & further reading

dev.to — original article Draku: Exorcising the Ghosts in Your Camera Roll with Offline Open-Weight AI 🦇 Building a Keyword Rank Tracker That Also Flags AI Overviews (Python) Heirloom: Bringing Our Ancestors’ Handwriting Back to Life