Haunted Shell: Possessing Your Terminal with Local Open-Weight AI (Ghost in the Machine)

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

---

What I Built & How I Interpreted the Theme

For this week's "Ghost in the Machine" theme, sitting right between Halloween and Día de los Muertos, I wanted to take the concept literally: What if a supernatural spirit lived inside your terminal, directly possessing your shell?

Introducing haunted-shell — an open-source, production-grade, local-first possessed terminal companion.

Whenever you run a command in your everyday shell (rm -rf, git push --force, kill -9, cat, whoami), an eerie spirit materializes, analyzing your command, exit code, and environment to whisper spooky commentary, roast dangerous commands, compose satirical calaveritas literarias in honor of computing ancestors, or scan the operating system's process table for real defunct zombie processes to exorcise.

To bridge Halloween and Día de los Muertos, haunted-shell comes with three distinct spirits:

1. The Poltergeist (poltergeist): A mischievous, chilling Halloween ghost who laughs at segfaults, mourns deleted inodes in /dev/null, and warns you of entities dwelling in ring 0.
2. La Calavera (calavera): A warm, philosophical Día de los Muertos spirit who scatters marigold (cempasúchil) petals on deleted files and writes witty poetic verses celebrating computing pioneers (Ada Lovelace, Grace Hopper, Alan Turing).
3. The 1971 PDP-11 Mainframe Specter (unix-elder): An ancient Bell Labs Unix ghost horrified by 80,000-file node_modules folders and multi-gigabyte browser memory leaks, longing for teletypes, pipes, and reel-to-reel magnetic tape.

---

Why Open Innovation Matters for haunted-shell

The challenge asks: Why does open innovation matter for what you built?

For a shell companion, open-source AI and local inference are not just nice-to-haves—they are an absolute security and functional prerequisite.

1. Absolute Air-Gapped Privacy for Shell Secrets: Your terminal is the most sensitive surface on your entire computer. It holds private SSH keys (~/.ssh), API tokens, environment variables ($AWS_SECRET_ACCESS_KEY), internal IP addresses, and proprietary code. If this tool were powered by a closed commercial cloud API (like OpenAI or Anthropic), every single command and argument would be transmitted across the internet to a third-party server. By using open-weight models (like Google Gemma 2) running entirely locally on-device, zero telemetry or command data ever leaves the laptop.
2. Works With the Lights (and the Internet) Off: Whether you are coding in an airplane cabin at 35,000 feet, in a remote server room, or during a storm with the WiFi down, haunted-shell doesn't skip a beat. It has zero cloud dependencies, zero external latency, and zero rate limits.
3. No Subscription Costs or Billing Meters: Developers type hundreds or thousands of shell commands every day. Routing those through paid proprietary cloud APIs would burn money. With local open-weight models, inference is 100% free forever.
4. Resilience & Custom Persona Freedom: Closed APIs suffer from sudden model deprecations and unpredictable system prompt overrides. Open weights can be fine-tuned, modified, and saved locally forever.

---

Demo & Live Experience

1. Interactive Possession Shell

Running haunt shell launches a possessed subshell with persistent readline history and directory tracking:

      .-.
     (o o) boo!
     | O \
      \   \      G H O S T   I N   T H E   M A C H I N E
       `~~~'     [ Possessed by local open-weight AI. Air-gap verified. ]

👻 Spirit: The Poltergeist of Purgatory
🔒 Air-gap Security: Verified Local-Only (Local Open-Weight Model [gemma2:2b])
💡 Type regular commands or ':help' for builtins. Type 'exit' to escape.

[haunted-shell] 👻 rm -rf old_drafts.txt
  👻  Gone. Banished to /dev/null. But in the graveyard of your disk, their sectors still whisper.

[haunted-shell] 👻 kill -9 4120
  👻  A cold-blooded slaughter... PID 4120 extinguished in an instant. Its orphan spirit lingers in kernel space.

[haunted-shell] 👻 git push --force origin main
  👻  You tear the fabric of shared memory without remorse. May the merge conflicts haunt your dreams.

2. Día de los Muertos Calaveras

Switching to --persona calavera (or typing :persona calavera live in the shell) turns your terminal into a remembrance altar:

[haunted-shell] 💀 git commit -m "Refactor parser"
  💀  Estaba la Catrina sentada en el disco / viendo tus commits con sonrisa y pellizco:
      '¡No te apures, dev, por ese merge conflict / que en el camposanto todo queda fixed!'

3. Real OS Zombie Process Exorcism with Safety Guardrails

haunt exorcise inspects the host operating system's kernel process table using psutil, hunting for true zombie processes, orphaned daemons, and memory-devouring wraiths, with built-in protections preventing accidental termination of PID 1 or host shells:

$ haunt exorcise
┌─[ SPECTRAL PROCESS NECROPSY ]────────────────────────────────────────────────────┐
│ Detected 3 restless entity/entities lurking in memory:                           │
│                                                                                  │
│ • PID 34646 [Memory Wraith] - Code Helper (Renderer)                             │
│   Memory: 200.7 MB | Age: 36.2 mins                                              │
│   "Devours 200.7 MB of physical memory like a restless devourer."                │
│                                                                                  │
│ • PID 41047 [Shadow Daemon] - language_server                                    │
│   Memory: 201.7 MB | Age: 8.3 mins                                               │
│   "Spawned in haste, abandoned in cold memory. It wanders kernel space..."       │
└──────────────────────────────────────────────────────────────────────────────────┘

To banish a restless PID, run: haunt exorcise --banish <PID>

4. Universal Shell Hooks (Zsh, Bash & Fish)

You don't even need to stay in a subshell. With haunt hook, your everyday terminal prompt automatically inherits the possession on every command you execute:

# For Zsh (~/.zshrc):
eval "$(haunt hook zsh)"

# For Bash (~/.bashrc):
eval "$(haunt hook bash)"

# For Fish (~/.config/fish/config.fish):
haunt hook fish | source

5. Environment Diagnostics (haunt doctor)

haunt doctor performs a rapid health audit of the host system, checking local Ollama connectivity, downloaded open-weight models, terminal color capability, and configuration status:

$ haunt doctor
┌─[ HAUNTED-SHELL SYSTEM DIAGNOSTICS ]─────────────────────────────────────┐
│ Platform: Darwin 27.2.0 (arm64)                                          │
│ Python:   3.14.3 (✓ Supported)                                           │
│ Terminal: Interactive TTY | Colors: ✓ Enabled | Size: 80x24              │
│                                                                          │
│ Active Persona:  poltergeist                                             │
│ Configured Model: gemma2:2b                                              │
│ Config File:      ~/.config/haunted-shell/config.json (Using Defaults)   │
│                                                                          │
│ Local AI Server (http://localhost:11434):                                │
│   ✓ Ollama reachable (1 model(s) available)                              │
│     Available: gemma2:2b                                                 │
└──────────────────────────────────────────────────────────────────────────┘

---

Technical Architecture & How It Works

haunted-shell was designed with clean Unix philosophy, strict typing, and resilient offline degradation:

┌────────────────────────────────────────────────────────┐
│                   User Shell Command                   │
└───────────────────────────┬────────────────────────────┘
                            │
              ┌─────────────▼─────────────┐
              │    Subprocess Execution   │
              └─────────────┬─────────────┘
                            │ (Exit code, CWD, Command tokens)
              ┌─────────────▼─────────────┐
              │       GhostEngine         │
              └──────┬─────────────┬──────┘
                     │             │
        (If available)             (Air-gapped fallback)
                     │             │
        ┌────────────▼──────┐   ┌──▼──────────────────────────┐
        │ Local Open-Weight │   │ Offline Spectral Engine     │
        │ Model (Gemma 2 via│   │ (Contextual matrices,       │
        │ Ollama/llama.cpp) │   │ calaveritas & glitch-zalgo) │
        └───────────────────┘   └─────────────────────────────┘

• Open-Weight Model Integration: Connects out of the box to local open-weight models (like Google Gemma 2:2B or Llama 3.2) hosted locally via Ollama (http://localhost:11434) or any local OpenAI-compatible endpoint.
• Zero-Dependency Fallback Engine: If no local model server is currently active, it automatically falls back to an offline semantic and poetic generator, ensuring it runs instantly on any machine with zero setup friction.
• Production Codebase:
  • Complete PEP 561 typing with py.typed and zero mypy errors.
  • Formatted and linted with Ruff.
  • Comprehensive unit test suite (59 tests passing, >75% coverage).
  • XDG configuration management (~/.config/haunted-shell/config.json).
  • GitHub Actions CI matrix testing across Ubuntu and macOS.

---

Partner Category Consideration

• Best Use of Gemma: Designed natively to run with Google's open-weight Gemma 2 (gemma2:2b / gemma2:9b), taking full advantage of Gemma's high instruction-following efficiency on consumer laptops!

---

Code Repository

The project is completely open source under the MIT license:

👉 GitHub: haunted-shell

Happy Halloween and ¡Feliz Día de los Muertos! May your terminals stay spooky and your memory leaks find peace.