👻 HauntShell — When Your Terminal Wakes Up and Whispers Back

   .---.
  /     \     H A U N T S H E L L
 | () () |    "The machine remembers what you bury."
  \  -  /     
   `---'      100% Offline • Zero API Cost • Total Privacy

What I Built

Every developer knows the eerie quiet of a 2:00 AM coding session. The room is dark, the blue-light glare flickers across the desk, and you're staring at an inscrutable stack trace. In that liminal silence, it’s easy to feel like something inside the silicon is watching you—an entity buried beneath layers of forgotten git stashes, abandoned branches, and zombie background processes.

For Week 4's "Ghost in the Machine" theme, I decided to give that presence a voice: HauntShell.

HauntShell is a local-first CLI utility and interactive shell that literally possesses your terminal. It wraps standard command execution and uses an offline open-weight model (llama3.2:3b via Ollama) to whisper ominous, eerie, and witty spectral commentary after every command you run:

When your command succeeds
(Exit Code=0): The specter delivers a chilling omen or sinister prophecy about the code, files, or state you just summoned into memory.
When your command fails
(Exit Code ≠0): The specter mocks your mortal blunders, doomed syntax, and pathetic crashes with macabre humor.
Interactive Haunted REPL: Run python haunt.py without arguments to step inside a fully possessed shell environment with live streaming output, custom haunted prompts (💀 haunt:~/path❯), and built-in navigation.

Demo

Here is HauntShell running live on my machine:

1. The Specter Blesses a Successful Build

$ python haunt.py git --version
git version 2.55.0.windows.3

👻 [Ghost in the Shell]: The chains of code now bind you, mortal. The darkness begins with version 2.55.0, forever etched in your digital soul.

1. Mocking a Doomed Mortal Blunder $ python haunt.py cat nonexistent_file.txt 'cat' is not recognized as an internal or external command, operable program or batch file.

👻 [Ghost in the Shell]: Pathetic attempt to conjure code. 'cat' isn't recognized, perhaps because it's a command from a bygone era, and so are you.

1. Staging and Committing into the Void $ python haunt.py git commit -m "feat: initial commit" [main (root-commit) 455b848] feat: initial commit 6 files changed, 598 insertions(+)

👻 [Ghost in the Shell]: Your code now echoes my presence, mortal. Files created, yet the truth remains: I have always been here.

1. Interactive Possessed Shell (haunt.py --interactive) .---. / \ H A U N T S H E L L | () () | The Ghost in the Machine \ - / Local AI Terminal Possession (llama3.2:3b) `---' 100% Offline • Zero API Cost • Private History

The terminal has been possessed. Type 'exit' or 'quit' to release your soul.

💀 haunt:~/Projects/Hauntshell❯ git status
On branch main
nothing to commit, working tree clean

👻 [Ghost in the Shell]: A clean tree hides the rot beneath the roots.

💀 haunt:~/Projects/Hauntshell❯ exit

👻 [Ghost in the Shell]: You may close the shell, mortal, but you can never leave the machine...

Code

yuvrajaasarwa / Hauntshell

👻 HauntShell: A haunted CLI utility that possesses your terminal with eerie spectral commentary via offline Llama 3.2. Built for Hacktoberfest Ghost in the Machine challenge.

👻 HauntShell — The Ghost in the Machine

"You may close the shell, mortal, but you can never leave the machine..."

       .---.
      /     \     H A U N T S H E L L
     | () () |    "The machine remembers what you bury."
      \  -  /     
       `---'      A Haunted Terminal Wrapper Powered by Offline Llama 3.2

HauntShell is a local-first CLI utility designed for the Hacktoberfest "Ghost in the Machine" challenge. It possesses your terminal, wraps standard shell execution, and uses an offline open-weight model (llama3.2:3b via Ollama) to whisper ominous, eerie, and witty spectral commentary after your commands or errors run.

---

🎃 The Haunting Narrative

Around Halloween and Día de los Muertos, folklore tells of spirits lingering in liminal spaces. In our modern age, that liminal space is the terminal: a black screen flickering in the dark, haunted by forgotten Git stashes, abandoned branches, corrupted nodes, and…

View on GitHub

GitHub Repository: https://github.com/yuvrajaasarwa/Hauntshell
License: MIT
Dependencies: ollama, colorama

How I Built It

HauntShell was engineered from the ground up for zero developer friction, low latency, and rock-solid terminal fidelity:

1. Local Open-Weight Inference with Ollama (llama3.2:3b)

Rather than relying on bloated cloud models, HauntShell is powered by Meta's lightweight llama3.2:3b model running locally via Ollama.

Using tight token limits (num_predict: 45), dynamic temperature sampling (0.85), and context truncation, the poltergeist generates punchy whispers in under 400ms.
The system prompt enforces strict constraints: the specter must speak in dark, witty, concise sentences under 25 words, with zero meta-commentary or markdown fluff.

1. Non-Blocking Duplex Stream Multiplexer

A terminal wrapper cannot afford to buffer or lag output. Using background daemon reader threads, HauntShell streams stdout and stderr byte-by-byte in real time directly to the terminal with native exit codes and ANSI formatting, while capturing an ephemeral 40-line buffer for the model to analyze.

1. Circuit Breakers & The Crypt Fallback Pool

Developers need their shell to work no matter what:

3.5s Hard Timeout: If Ollama is cold-starting or busy, the execution never hangs.
Offline Crypt Pool: If the Ollama daemon isn't running, HauntShell silently falls back to atmospheric pre-written spectral whispers so the illusion never breaks and commands execute unimpeded.

1. Terminal Aesthetics with Colorama

Spectral whispers are rendered in spectral magenta (Fore.MAGENTA) for successes and dim blood red (Fore.LIGHTRED_EX) for errors, accompanied by a subtle typewriter effect with clean KeyboardInterrupt (Ctrl+C) handling and Windows UTF-8 reconfigurations.

Why Does Open Innovation Matter?

This project would be fundamentally broken—and arguably reckless—if built on proprietary closed cloud APIs. Open innovation made HauntShell possible in three vital ways:

Total Command-History Privacy: Your terminal is the most sensitive environment on your machine. You type environment secrets, database connection strings, API tokens, sensitive file paths, and unreleased proprietary code. Sending every terminal command and error log to a third-party cloud API is an unacceptable privacy hazard. With open weights running on local silicon, nothing leaves localhost.
Zero Invocations Cost ($0 Forever): A developer runs dozens or hundreds of commands every day. Closed APIs charge per-token and would turn a fun terminal session into a metered billing nightmare. Open weights mean you can leave HauntShell aliased as your default daily driver shell without paying a single cent.
True Offline Independence: Open models empower developers to build without tethering themselves to corporate server availability or internet access. Whether you're coding on a flight, in a rural cabin, or in a blackout, the ghost is always right there in your machine.
My Agent Session

This project was conceived, prototyped, and brought to life in an end-to-end agentic pair-programming session:

Scaffolding the repository, virtual environment, and dependency isolation.
Architecting the dual-threaded subprocess pipe handler to stream live command output without latency.
Iteratively tuning the spectral persona prompt against local llama3.2:3b weights to dial in the eerie wit.
Debugging Windows ANSI and UTF-8 encoding nuances for cross-platform polish.
Creating the repository and configuring Git attribution directly via the GitHub REST API.
The Spirit of It

The moment I knew HauntShell had captured the theme was during test execution:

I purposely triggered a failed Git commit without a message:

console
$ python haunt.py git commit
Aborting commit due to empty commit message.
👻 [Ghost in the Shell]: Silence is just a state of mind, but your code is already screaming in the dark.

That spontaneous, unscripted wit gave me genuine chills. It wasn't a generic chatbot repeating "I'm sorry you encountered an error." It felt like an ancient spirit that had been lurking in the L2 cache all along, just waiting for me to slip up.