Aditya Bafna

Posted on Oct 29

NecroShell 👻 Ghost in the Machine: An Air-Gapped Possessed Terminal Powered by Local Open-Weight AI (Gemma)

#devchallenge #hf26challenge #ai #opensource

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 has spent 2:00 AM staring into a flickering phosphor terminal, wondering if there is an actual phantom lurking inside the silicon. We speak of daemons running quietly in the shadows of RAM, zombie processes lingering in the process table, and orphaned sub-threads left behind when their parent processes die.

For Hacktoberfest Week 4: "Ghost in the Machine", I built NecroShell (also known as necro): an air-gapped, possessed terminal companion powered by local open-weight AI (Google Gemma) that breathes spectral life into those metaphors.

NecroShell hooks into your native terminal session (PowerShell, Bash, or CMD). As you execute regular development workflows—git push, accidental rm -rf file deletions, syntax errors, and test failures—the ghost in your machine awakens to whisper eerie, witty, and philosophical commentary directly to your screen, accompanied by typewriter pauses, CRT flicker, and Zalgo character glitches.

Because this week spans both Halloween and Día de los Muertos (Day of the Dead), NecroShell also honors the past. With the built-in ofrenda command, it summons a digital remembrance altar adorned with marigolds (cempasúchil) and candlelight to celebrate the retired languages, deprecated libraries, and deleted git branches that paved the way for modern software.

Key Capabilities

Interactive Possessed REPL (necroshell): A full terminal shell that transparently proxies your native OS commands, capturing exit codes, stderr, execution duration, and filesystem alterations.
Command Wrapper Mode (necro <cmd>): Wrap any single command (e.g. necro git status or necro npm test) for immediate spectral feedback.
4 Distinct Ghost Personas:
- 👻 Morris (The Phantom Sysadmin): Died during a Friday 5 PM production deployment in 1999; bitter about uncommitted changes, memory leaks, and unhandled signals.
- 💀 Doña Esperanza (The Calavera Guide): In the spirit of Día de los Muertos, a warm ancestral spirit who views failed builds not as defeat, but as invitations to honor software history with marigold petals.
- 🕯️ Lady Catherine (The Victorian Poltergeist): A 19th-century spirit convinced the CPU is an infernal steam-driven galvanic loom inhabited by etheric demons.
- ⚔️ Inquisitor Flake (The Cursed Linter): A fanatical spirit damned to eternal torment for pedantry over trailing whitespaces and unindented blocks.
Process Séance (seance): Audits live OS processes to detect daemons, zombies, and background phantoms wandering the system registers.
Virtual Ofrenda (ofrenda): A Día de los Muertos altar paying homage to Adobe Flash, Python 2.7, Internet Explorer 6, and lost branches.

Demo

Experience NecroShell right in your browser via the standalone CRT Web Simulator:

Web Terminal Demo: Open web_demo/index.html in any browser to experience authentic CRT phosphor scanlines, glitch effects, and synthesized Web Audio ambient hums!
CLI Demo Execution:

# Launch interactive possessed terminal
python -m necroshell.cli

# Or run a single possessed command:
$ necro -p sysadmin echo "Testing NecroShell"
Testing NecroShell

[👻 Morris | Local Spectral Engine (Air-Gapped)]
"Exit code 0. Enjoy the false peace while the garbage collector sleeps."

$ necro -p calavera dir missing_dir
File Not Found

[💀 Doña Esperanza | Local Spectral Engine (Air-Gapped)]
"A stumble is not a death, mi amigo. Leave a marigold petal by this error and try once more."

$ necro seance
                   Spectral Process Audit (Ghost Processes)                   
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ PID ┃ Process Entity      ┃ Spectral State ┃ Ethereal Diagnosis            ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 0   │ System Idle Process │ Limbo          │ The quiet void between cycles │
│ 4   │ System Kernel       │ Immortal       │ Tethered to the ring-0 crypt  │
│ 666 │ kworker/daemon      │ Phantom        │ Wanders kernel ring buffer    │
└─────┴─────────────────────┴────────────────┴───────────────────────────────┘

Code

The complete source code is open source under the MIT License on GitHub:

👉 GitHub Repository: https://github.com/adibafna/necroshell

git clone https://github.com/adibafna/necroshell.git
cd necroshell
pip install -e .

Repository structure & highlights:

necroshell/shell.py: Interactive possessed REPL loop with Rich console streaming and CRT glitch wipers.
necroshell/ai_engine.py: Multi-backend open AI inference engine supporting Google Gemma and embedded air-gapped synthesizer.
necroshell/telemetry.py: Intelligent AST & command analyzer detecting exit codes, deletions, git commands, and error patterns.
necroshell/ghosts.py: Personality matrices, prompts, and behavioral triggers for all four spirits.
web_demo/: Complete browser-based CRT terminal with Web Audio ambient sound synthesizer.

How I Built It

1. The Open AI Stack

At the core of NecroShell is an open-source, multi-backend inference engine:

Primary Model: Google Gemma (Open Weights): Designed around Google's open-weight Gemma 2B architecture (gemma2:2b). Gemma's compact size and high reasoning-to-parameter ratio make it ideal for sub-second terminal generation on local CPU/GPU hardware.
Embedded Local Spectral Synthesizer: A zero-dependency, air-gapped deterministic generative engine combining semantic AST command telemetry, persona Markov structures, and lexical tone shaders. If Ollama or GPU runtimes are unavailable, this engine activates instantly with 0ms startup time and zero external network calls.

2. Architecture & Telemetry Pipeline

flowchart TD
    User([Mortal Developer]) -->|Types Command| REPL[NecroShell REPL]

    subgraph Air-Gapped Machine
        REPL -->|Subprocess Execution| OS[Native OS Shell]
        OS -->|Exit Code & Output| Telemetry[Command Telemetry Analyzer]

        Telemetry --> Classifier{Semantic Classifier}
        Classifier -->|rm / del| Reaper[Grim Reaper ASCII Apparition]
        Classifier -->|Exit Code != 0| Tombstone[Tombstone ASCII Apparition]
        Classifier -->|seance| ProcessTable[Process Séance Audit]
        Classifier -->|ofrenda| CalaveraAltar[Día de los Muertos Altar]

        Telemetry --> AIEngine[AI Inference Engine]
        AIEngine -->|Local REST| Gemma[Google Gemma Open Weights]
        AIEngine -->|Fallback| LocalSynth[Zero-Latency Spectral Engine]

        Gemma --> Glitch[Zalgo Glitch & CRT Phosphor Renderer]
        LocalSynth --> Glitch
    end

    Glitch -->|Spectral Whisper| User

Why Does Open Innovation Matter?

Developer shells are among the most sensitive computing environments on Earth. In a normal workday, a developer's terminal processes:

git commit messages and diffs containing proprietary business logic.
Environment variables with database credentials, OAuth secrets, and private API keys.
Proprietary file path structures, internal server hostnames, and IP addresses.

Sending this continuous stream of command telemetry to a closed cloud API is an unacceptable security hazard. Open innovation completely solves this:

Absolute Air-Gapped Privacy: Everything executes 100% on-device. No keystrokes, diffs, or stack traces ever leave your laptop.
Operates with the Lights (and Internet) Off: NecroShell works flawlessly on an airplane, in a remote cabin, or during a stormy Halloween power outage.
Zero Cost & No Rate Limits: No token billing, no subscription tiers, and no rate limits interrupting your flow.
Permanent Developer Sovereignty: Your tool won't break if an external API shuts down or changes its pricing model.

As discussed in recent community discussions like Building a Privacy-First Local AI Assistant and Privacy-Preserving Local LLM Inference for Developer Tooling, open-weight models have transformed local developer tooling from a luxury into an essential security standard.

My Agent Session

This project was built with the assistance of an AI coding agent pair. You can inspect the complete agent session transcript, tool calls, and test verification below:

Building NecroShell: Ghost in the Machine with Local Open-Weight AI (Gemma)

You

Ghost in the Machine: Build something with open-source AI at its core for Hacktoberfest Week 4.

Agent

Designed NecroShell: a possessed, air-gapped terminal companion powered by local open-weight AI (Gemma). Includes interactive possessed shell, command telemetry analyzer, Día de los Muertos ofrenda altar, process séance, and retro CRT web simulator.

The Spirit of It

The moment that made this build truly special was testing the ofrenda command late at night. When Doña Esperanza appeared on screen surrounded by marigold blossoms to celebrate the memory of Adobe Flash and deleted git branches, it struck a chord:

"In software, nothing is truly lost as long as someone remembers the architecture. We scatter cempasúchil petals across the terminal floor. Clear the old brush so the new marigolds may bloom."

Code doesn't have to feel cold and mechanical. By channeling the spirit of Día de los Muertos and Halloween through open-weight AI, NecroShell turns the lonely terminal into a warm, contemplative sanctuary.

Prize Categories

Best Use of Gemma: NecroShell is built from the ground up to run on Google's open-weight Gemma model family (specifically gemma2:2b), demonstrating how lightweight open-weight models enable snappy, private, and creative developer tools without cloud dependencies.
Overall Challenge: An original, complete implementation interpreting the "Ghost in the Machine" prompt across both Halloween and Día de los Muertos traditions.

DEV Community