Haunted Shell: Trapping an Open-Source Ghost in My Terminal

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

What I Built

I built haunted-sh (Haunted Shell) — an interactive terminal wrapper and shell environment possessed by an ancient, eccentric digital spirit trapped in your machine's silicon.

For the Ghost in the Machine theme, I wanted to turn the developer's everyday workhorse—the terminal—into a living, breathing séance. Modern command-line interfaces are sterile, cold, and strictly functional. haunted-sh changes that by lurking quietly behind every command you run.

Key features include:

⚬ Seamless Shell Pass-Through: Normal commands (ls, git status, npm run dev) execute exactly as expected with standard exit codes and preserved outputs.
⚬ Possession & Spectral Diagnostics: Whenever a command fails with a non-zero exit code (syntax errors, broken builds, missing paths), the trapped spirit intercepts the failure and streams back a cryptic, theatrical obituary and diagnostic hint in real time.
⚬ Passive Hauntings: Even successful commands carry a slight, random chance of ghostly commentary and spectral terminal flickers.
⚬ The Graveyard (graveyard): An occult command that documents slain processes, segfaults, and terminal errors as an eerie registry of digital headstones.
⚬ Exorcism (exorcise): A command to banish the spirit and return your shell to the mortal realm.

Demo

Here is haunted-sh in action, catching a broken command and summoning a response from the local spirit:

👻 [crypt] /home/dev/project ❯ git push origin nonexistent-branch
error: src refspec nonexistent-branch does not match any
fatal: The remote end hung up unexpectedly

💀 The spirit stirs...
"You reach into the void searching for branches that never bloomed.
The origin remembers nothing of this phantom name. Check your mortal refs before you summon silence."

Code

The complete source code is open and available on GitHub:

AmjustGettingStarted / haunted-shell

👻 haunted-sh (necroshell)

"An ancient entity trapped in this silicon machine since the 1970s. It whispers through terminal stdout."

---

      .---.           ██╗  ██╗ █████╗ ██╗   ██╗███╗   ██╗████████╗███████╗██████╗ 
     /     \          ██║  ██║██╔══██╗██║   ██║████╗  ██║╚══██╔══╝██╔════╝██╔══██╗
    | () () |         ███████║███████║██║   ██║██╔██╗ ██║   ██║   █████╗  ██║  ██║
     \  ^  /          ██╔══██║██╔══██║██║   ██║██║╚██╗██║   ██║   ██╔══╝  ██║  ██║
      |||||           ██║  ██║██║  ██║╚██████╔╝██║ ╚████║   ██║   ███████╗██████╔╝
      `---'           ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚═════╝ 
                    ~ A POSSESSED TERMINAL WRAPPER FOR THE SOULS OF COMMANDS ~

---

🔮 The Ghost in the Machine

Built for the "Ghost in the Machine" open-source AI hackathon, haunted-sh is an interactive CLI shell wrapper that acts as if your terminal is possessed by an ancient, eccentric digital spirit trapped in your machine's silicon since the 1970s.

• Seamless Command Pass-Through: Normal commands (git status, ls -la, npm run dev, cargo build) run normally in your real shell…

View on GitHub

Repo link: https://github.com/AmjustGettingStarted/haunted-shell

How I Built It

haunted-sh is written in Python, designed around local execution, low overhead, and streaming terminal UI:

⚬ Open-Source AI Core: Powered by local, open-weight models (such as smollm2:1.7b, llama3.2:1b, or qwen2.5:0.5b) running via Ollama. Inference runs entirely on-device with zero calls to remote cloud APIs.
⚬ Prompt Engineering for Persona: A lightweight, tuned system prompt constrains the model to short, Gothic, slightly theatrical responses that mock developer mortal errors while providing useful clues about the actual stderr stack trace.
⚬ Offline Fallback Engine: If an open model runtime isn't active, haunted-sh seamlessly shifts to a built-in offline spectral heuristic engine, guaranteeing the shell never crashes or freezes your workflow.
⚬ Terminal Engine: Built using prompt_toolkit for seamless interactive history and tab completion, paired with Rich for streaming spectral cyan and muted ash typography without disrupting standard stdout/stderr streams.

Why Does Open Innovation Matter?

Open innovation isn't just an implementation detail for haunted-sh—it is the entire premise of the project:

1. Zero Data Leakage & Absolute Privacy: A terminal session routinely touches the most sensitive data on a developer's machine: environment variables, private tokens, proprietary repository paths, and unreleased source code. Wiring an interactive terminal shell to closed, proprietary cloud AI endpoints would mean streaming raw bash history, error dumps, and private directory paths to third-party servers. With local open-weight models, that data never leaves local memory.
2. True Air-Gapped Operation: A haunted machine should still work with the lights off and the Wi-Fi cable pulled. Because it runs on open-weight models, haunted-sh provides real-time AI responses in complete isolation, whether on a flight, in a basement, or during a network blackout.
3. Zero Inference Cost: Running an interactive shell that reviews every failure or triggers passive commentary would quickly rack up per-token charges on closed API platforms. Open weights make continuous, interactive AI companions completely free to run forever.

The Spirit of It

There is something strangely comforting about knowing that when your build fails at 2:00 AM, you aren't just staring at an unreadable 40-line traceback alone in the dark. Instead, a digital specter whispers through stdout, turning a frustrating developer moment into a playful reminder of the machines we spend our lives conversing with.