{"slug": "phantom-exe", "title": "Phantom.exe", "summary": "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.", "body_md": "*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)*\n\n## \n  \n  \n  What I Built\n\nI 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.\n\nThe central premise behind **PHANTOM.exe**:\n\n*\"What if your abandoned codebase had a ghost that remembered everything?\"*\n\nEvery 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.\n\n### \n  \n  \n  Core Capabilities\n\n1. \n**🔦 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.\n2. \n**👻 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.\n3. \n**🕯️ 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)** .\n4. \n**🧪 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.\n5. \n**📜 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.\n6. \n**🔒 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.\n\n## \n  \n  \n  Demo\n\n### \n  \n  \n  Sample Ghost Transmission (SpecterAuth Abandoned Repository)\n\n### \n  \n  \n  Interactive 7-View Cyberpunk CRT Dashboard (`http://localhost:8501`)\n\n- \n**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.\n- \n**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.\n- \n**3. Ghost Chat:** Streaming neural séance terminal with one-click preset prompts (*\"What happened here?\"* ,*\"Unfinished functions\"* ,*\"Security & Bugs\"* ,*\"Explain TODOs\"* ).\n- \n**4. Digital Memories:** Side-by-side Verified Git Facts vs. PHANTOM Memory Whispers, commit activity chart, hotspot/dormant file tables, and commit timeline.\n- \n**5. Paranormal Debugger:** Severity/category filters and per-finding AI explanations.\n- \n**6. Last Words:** Post-mortem revival report with raw Markdown preview and`.md` download.\n- \n**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.\n\n## \n  \n  \n  Code\n\n### \n  \n  \n  Quick Start\n\n## \n  \n  \n  How I Built It\n\n### \n  \n  \n  Architecture\n\nBoth 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.\n\n```\nflowchart LR\n    subgraph UI[\"Streamlit Dashboard (frontend/dashboard.py)\"]\n        ST_UI[\"7 Interactive CRT Terminal Views\"]\n    end\n\n    subgraph API[\"FastAPI Server (app/api/routes.py)\"]\n        REST[\"REST Endpoints (/api/*)\"]\n    end\n\n    subgraph SVC[\"Unified Service Layer (app/core/service.py)\"]\n        PS[\"PhantomService\"]\n        SCN[\"HauntedScanner (Python AST + Heuristics)\"]\n        GIT[\"GitAnalyzer (GitPython + Git CLI)\"]\n        DBG[\"ParanormalDebugger\"]\n        RPT[\"LastWordsGenerator\"]\n        CTX[\"RepositoryContextBuilder + redact_secrets()\"]\n    end\n\n    subgraph LOCAL[\"100% Local Persistence & Inference\"]\n        DB[(\"SQLite (data/phantom.db)\")]\n        OL[[\"Ollama Local Server (qwen2.5:3b)\"]]\n        FS[(\"Target Local Repository (Read-Only)\")]\n    end\n\n    ST_UI --> PS\n    REST --> PS\n    PS --> SCN\n    PS --> GIT\n    PS --> DBG\n    PS --> RPT\n    PS --> CTX\n    SCN --> FS\n    GIT --> FS\n    CTX --> OL\n    PS <--> DB\n```\n\n### \n  \n  \n  Technology Stack & Key Engineering Decisions\n\n- \n**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.\n- \n**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.\n- \n**Defense-in-Depth Privacy & Security Hardening:**  - Enforced path containment (`is_safe_subpath` ) and symlink skipping so scans cannot escape the target repository root.\n  - Enforced loopback-only Ollama URL validation (`validate_ollama_host` ) by default across all UI and API entrypoints.\n  - 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.\n- \n**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.\n- \n**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` ).\n\n## \n  \n  \n  Why Does Open Innovation Matter?\n\nDeveloper 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.\n\nOpen-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:\n\n1. \n**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.\n2. \n**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.\n3. \n**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.\n\n## \n  \n  \n  My Agent Session\n\nI pair-programmed with **Antigravity** across an iterative architecture, implementation, security review, and verification workflow:\n\n1. \n**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` ).\n2. \n**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.\n3. \n**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` ).\n  - Added strict loopback host validation (`validate_ollama_host` ) with explicit remote opt-in warnings so query/request overrides cannot silently exfiltrate repository context.\n  - 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.\n  - 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` ).\n4. \n**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` .\n\n## \n  \n  \n  The Spirit of It\n\n**PHANTOM.exe** embraces the *\"Ghost in the Machine\"* theme both aesthetically and functionally:\n\n- 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).\n- 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.\n\n## \n  \n  \n  Prize Categories\n\n- \n**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.\n- \n**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.\n- \n**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.", "url": "https://wpnews.pro/news/phantom-exe", "canonical_source": "https://dev.to/mayukhjyotisarkar/phantomexe-3iad", "published_at": "2026-10-31 15:09:11+00:00", "updated_at": "2026-10-31 15:22:42.213977+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "developer-tools", "large-language-models", "ai-safety"], "entities": ["PHANTOM.exe", "Ollama", "qwen2.5:3b", "qwen2.5-coder:7b", "GitPython", "Hacktoberfest"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/phantom-exe", "markdown": "https://wpnews.pro/news/phantom-exe.md", "text": "https://wpnews.pro/news/phantom-exe.txt", "jsonld": "https://wpnews.pro/news/phantom-exe.jsonld"}}