This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine
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 s, 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.
necroshell) necro <cmd>) necro git status or necro npm test) for immediate spectral feedback. seance) ofrenda)
Experience NecroShell right in your browser via the standalone CRT Web Simulator:
web_demo/index.html in any browser to experience authentic CRT phosphor scanlines, glitch effects, and synthesized Web Audio ambient hums!
python -m necroshell.cli
$ 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 │
└─────┴─────────────────────┴────────────────┴───────────────────────────────┘
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.
At the core of NecroShell is an open-source, multi-backend inference engine:
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.
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
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.
Sending this continuous stream of command telemetry to a closed cloud API is an unacceptable security hazard. Open innovation completely solves this:
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.
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:
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.