DEV Community

Raj Jasani
Raj Jasani

Posted on

GhostShell AI — Hacktoberfest Week 4: Ghost in the Machine

#devchallenge #hf26challenge #hacktoberfest #ai

Hacktoberfest Open-Source AI Challenge: Ghost in the Machine Submission 👻🌼

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

🔮 What I Built

Every developer knows the eerie sensation of working in a legacy codebase: functions that haven't been invoked in half a decade, error handlers that swallow exceptions into the dark void, and departed software technologies that continue to linger like phantoms in our tech stack.

To celebrate Hacktoberfest 2026 Week 4 and honor both Halloween and Día de los Muertos, I created GhostShell AI — an open-source, local-first possessed terminal companion and codebase séance engine.

GhostShell AI embodies the "Ghost in the Machine" across three thematic pillars:

  1. The Haunted Terminal Companion (ghost possess / ghost shell): Possesses your interactive shell session, intercepting command execution, exit codes, and output to whisper atmospheric, witty gothic commentary and necrotic diagnostics directly to the terminal.
  2. The Codebase Séance Engine (ghost seance): Performs a deep AST (Abstract Syntax Tree) spiritual post-mortem on Python files and repositories. It unearths "zombie functions" (defined but never summoned), "silent tombs" (except: pass), forgotten TODO gravestones, and infinite loop traps, calculating a composite Haunting Score (0% to 100%) and producing AI-guided exorcism recommendations.
  3. The Digital Ofrenda (ghost ofrenda): In the tradition of Día de los Muertos, provides a digital altar to honor and commemorate retired technologies, sunsetted APIs, and vintage artifacts (such as Adobe Flash Player, IE6, Python 2.7, and 3.5" floppy disks) with poetic AI-synthesized eulogies and traditional offerings (cempasúchil marigold bytes, amber candles, and sugar calaveras).
  4. Cyber-Gothic Web Dashboard (ghost serve): A responsive dark-mode dashboard with glowing spectral animations, a live interactive possessed shell simulator, code séance analyzer, and interactive ofrenda gallery. 
flowchart TD
    subgraph Input ["💻 Developer Inputs"]
        A1["Interactive Shell Commands\n(exit codes, stdout, stderr)"]
        A2["Source Codebase & Scripts\n(Python AST / Files)"]
        A3["Sunsetted Tech Memories\n(Deprecated APIs & Frameworks)"]
    end

    subgraph Core ["🔮 GhostShell Core Engine"]
        B1["HauntedTerminal Subprocess Monitor"]
        B2["CodebaseSeance AST Necrotic Inspector"]
        B3["DigitalOfrenda Altar Manager"]
    end

    subgraph AI ["🧠 Open-Source AI Layer"]
        C1["Local Open-Weight Model\n(Ollama Gemma 2 / Llama 3.2)"]
        C2["Deterministic Spectral Engine\n(Offline Resilient Fallback)"]
    end

    subgraph Output ["🖥️ Developer Experiences"]
        D1["Possessed Terminal CLI\n(Spectral Whispers & Altar Cards)"]
        D2["Cyber-Gothic Web Dashboard\n(http://localhost:8765)"]
    end

    Input --> Core
    Core <--> AI
    C1 <--> C2
    Core --> Output

📸 Demo & Terminal Walkthrough

GhostShell AI is designed to run seamlessly from the command line or via an ambient web interface:

1. Possessed Shell Execution Demo 

$ python3 -m ghostshell.cli possess "cat missing_necronomicon.txt"
cat: missing_necronomicon.txt: No such file or directory

🔮 [Ghost in the Machine]: The necrotic register shivers. Exit code 1 whispers of an unhandled curse in `cat missing_necronomicon.txt`.

$ python3 -m ghostshell.cli possess "git commit -m 'Initial summon'"
[main (root-commit) 9a8c359] Initial summon
 16 files changed, 1420 insertions(+)

🔮 [Ghost in the Machine]: A timeline altered. The git graph remembers all who were staged, committed, and abandoned in detached HEAD states.
Enter fullscreen mode Exit fullscreen mode

2. Codebase Séance Diagnostic Output 

$ python3 -m ghostshell.cli seance examples/cursed_code.py
=================================================================
🔮 SÉANCE REPORT: examples/cursed_code.py
=================================================================
• Haunting Score: 78.5%
• Spiritual Classification: Catastrophically Cursed (Necrotic Poltergeist Activity)
• Issues Found: 4

--- Detected Anomalies ---
  [LOW] Line 3: Cryptic marker found: '# TODO: Investigate memory leak reported in Q3 2024'
  [MEDIUM] Line 7: Zombie function `ancient_forgotten_zombie_routine` is defined but never summoned in this file.
  [HIGH] Line 15: Cursed bare `except:` swallows system daemons and hides memory corruption.
  [MEDIUM] Line 16: Silent `except ... pass` creates a tomb where runtime errors die silently.

--- Necrotic AI Diagnosis & Exorcism Plan ---
Post-Mortem Analysis for `cursed_code.py`:
Observed 4 spiritual anomaly(ies) lingering in the syntax tree.
Found 1 Zombie Function(s): Defined in the source yet never summoned during runtime.
Detected 1 Cursed Pattern(s): Bare exception silencers and dangerous memory bindings.
Verdict: The codebase harbors restless spirits. Perform exorcism to restore memory purity.
=================================================================
Enter fullscreen mode Exit fullscreen mode

3. Digital Ofrenda Altar Tribute 

$ python3 -m ghostshell.cli ofrenda --name "Adobe Flash Player"
=================================================================
🕯️  DIGITAL OFRENDA: Adobe Flash Player (1996 - 2020)
Category: Interactive Web & Animation
=================================================================
Offerings on the Altar: 🌼 Golden Vector Marigold | 🕯️ 60fps Phosphor Flame | 🍬 SWF Sugar Skull

You brought sound and movement to a static web of plain text. Generations of indie game developers and animators took their first steps in your timeline. Though security daemons claimed your runtime, your creative spirit echoes across the modern canvas.
=================================================================
Enter fullscreen mode Exit fullscreen mode

🛠️ How I Built It

Open-Source AI & Open-Weight Runtimes

  • Open-Weight Model Integration: GhostShell natively integrates with local open-weight models via Ollama (gemma2:2b, llama3.2, mistral, or phi3). No tokens are sent to external third-party proprietary clouds.
  • Deterministic Spectral Fallback Engine: If Ollama or GPU runtimes are unavailable, GhostShell immediately switches to a built-in deterministic spectral inference engine. This ensures the application works 100% offline with zero external pip dependencies.

Architecture & Tech Stack

  • Python Standard Library Core: Uses Python 3.9+ ast for parsing Abstract Syntax Trees, subprocess for POSIX command interception, http.server with multithreading for the local dashboard backend, and urllib for zero-dependency local model querying.
  • Cyber-Gothic Web Interface: Built with modern CSS (glassmorphism, CSS grid, glowing pseudo-elements) and vanilla JavaScript. Features a simulated possessed CRT terminal, real-time code auditor, and an altar memorial gallery.
  • Rigorous Testing: Backed by a comprehensive 16-test suite using Python's unittest framework with 100% passing results.

🌐 Code & Repository

To run GhostShell AI locally in 10 seconds:

git clone https://github.com/rajJasani/ghostshell-ai.git
cd ghostshell-ai
python3 -m unittest discover -s tests -p "test_*.py" -v
python3 -m ghostshell.cli serve --port 8765
Enter fullscreen mode Exit fullscreen mode

💡 Why Open Innovation Matters

The rapid rise of cloud-hosted, proprietary AI APIs presents serious concerns for developer privacy, tool longevity, and system reliability:

  1. Terminal Privacy and Code Security: Shell history and developer terminals frequently contain sensitive information: internal staging paths, database connection strings, tokens, and proprietary source code. Piping terminal output into closed, multi-tenant cloud APIs is unacceptable in security-conscious workflows. By leveraging local open-weight models, GhostShell ensures that zero bytes leave the developer's workstation.
  2. Offline Autonomy ("Ghost in the Silicon"): Software should function on a plane, in a basement server room, or during internet disruptions. An AI-powered developer tool that stops working when the Wi-Fi drops fails the core principle of developer sovereignty.
  3. Digital Preservation & Open Knowledge: Just as open-source preserves old code from disappearing into proprietary corporate archives, open-weight models ensure that developer assistance remains democratized, unmetered, and perpetually accessible to all builders worldwide.

Top comments (0)