Phantom.exe

A developer built PHANTOM.exe, an open-source, local-first AI coding companion and static repository forensics tool that analyzes abandoned codebases for unfinished functions, TODO/FIXME markers, syntax errors and Git history without executing target code. The tool runs open-weight models locally through Ollama (qwen2.5:3b by default) to generate a persona-driven analysis grounded in repository telemetry, falling back to a deterministic mode when Ollama is offline, and enforces a loopback-only inference boundary with secret redaction and exclusion of sensitive files.

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine https://dev.to/challenges/hacktoberfest-week4-2026-10-26 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 uploading 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 1. 🔦 Haunted Codebase Scanner: Static, read-only repository forensics using Python's ast module and multi-language heuristics across 35+ extensions . It detects pass stubs, ... Ellipsis placeholders, functions raising NotImplementedError , empty classes, mutable default arguments, bare except: clauses, confirmed SyntaxError s, TODO / FIXME / HACK / BUG markers, and orphan backup files—computing a Codebase Health Score 0–100 and Haunt Level without ever importing or executing target repository code. 2. 👻 The Ghost AI Local Ollama Inference : Powered by open-weight language models running locally via Ollama qwen2.5:3b by default, configurable to qwen2.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 deterministic Echo Fallback Mode while keeping all static analysis features 100% operational. 3. 🕯️ Digital Memories Git Forensics : Dual-engine Git history analyzer GitPython + native git 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 separating Verified Git Facts Objective from PHANTOM'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, catching pass and ... stubs, NotImplementedError branches, empty classes, mutable default arguments def fn cache= , bare except: blocks, and exact line/column SyntaxError s. - Ollama + qwen2.5:3b Open-Weight Inference: Implemented OllamaClient over httpx 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: Built GitAnalyzer to inspect local .git repositories without walking into parent directories search parent directories=False , using ASCII unit separators \x1f in git 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: 1. True Code Sovereignty & Privacy: When debugging a stalled repository or auditing legacy code for security issues and forgotten FIXME s, developers often work with sensitive codebases that cannot legally or safely leave their machine. Running open-weight models on localhost 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 clone PHANTOM.exe , pull qwen2.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: 1. 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 make PHANTOM.exe immediately testable out of the box, we built a realistic abandoned microservice fixture SpecterAuth in data/sample abandoned auth service containing unfinished MFA/token-rotation functions, a mid-edit SyntaxError , 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 so qwen2.5:3b never falsely matches qwen2.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 . 4. 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, detached HEAD , shallow clones, truncated history , and FastAPI HTTP endpoints via httpx.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 atmospheric neural 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 places Verified Git Facts side-by-side with PHANTOM's Memory Whispers , Paranormal Debugger distinguishes confirmed AST syntax errors from static heuristic indicators, and the Last Words generator transforms a haunted codebase's unfinished functions and lingering TODO 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 via Ollama 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.