DEV Community

DHRUV GUPTA
DHRUV GUPTA

Posted on

Haunted Shell: Communing with Dead Code & Crashed Processes via Local Gemma 3

#devchallenge #hf26challenge #ai #opensource

Hacktoberfest Open-Source AI Challenge: Ghost in the Machine Submission 👻🌼

This article is submitted for the Hacktoberfest Open-Source AI Challenge: Week 4 (Theme: Ghost in the Machine).

👻 What I Built: Haunted Shell

Every git repository is an obituary column. Behind every clean main branch lie buried functions, excised logic, hasty hotfixes, and broken promises commemorated in cryptic commit messages. And when builds crash or tests fail, those buried spirits wail through unholy stack traces.

Haunted Shell is a lightweight, zero-dependency Node.js command-line medium that awakens the Spectral Chronicler—a Victorian necromancer inhabiting your terminal. It connects your git diffs, excised code, and crashed process stderr logs to Google Gemma 3 running 100% locally via Ollama (http://localhost:11434/v1/chat/completions) or LM Studio.

         ___
        /   \
       | o o |
       |  ^  |
       | '-' |
        \   /
      __|   |__
     /  |   |  \
    /   | . |   \
   (    (   )    )
    '---'   '---'
Enter fullscreen mode Exit fullscreen mode

🔮 The Three Spectral Rites

Haunted Shell provides three specialized commands:

1. haunted-shell autopsy

Performs a forensic post-mortem on the git graveyard. It scans recent commits, extracts excised lines (- diffs), inspects working tree wounds, and invokes Gemma 3 to deliver:

  • The Exhumation: Summary of what functionality was killed and buried.
  • Haunted Bug Warnings: Latent regressions or broken references introduced by recent deletions.
  • The Healing Rite: Practical git actions and code fixes to restore peace to the codebase.

Live Terminal Transcript: 

$ haunted-shell autopsy

⚰️  BEGINNING POST-MORTEM AUTOPSY ON THE REPOSITORY...
Inspecting branch 'main', recent commits, and deleted code tombs...

(A chilling gust of wind rustles through the repository...)

Hark! I, the Spectral Chronicler, have surveyed the wreckage. 
The echoes of these revisions… disturbing.

1. The Exhumation (Summary of What Was Killed)
The recent activity reveals a frantic attempt to deliver a "zero-dependency haunted-shell CLI". 
The initial commit appears to be a rudimentary placeholder. The subsequent addition represents 
a complete architecture. Crucially, empty fields from package.json were deliberate removals.

2. Haunted Bug Warnings (Specific Defects & Regressions)
• Regression: Absence of Testing: The "Error: no test specified" test remains.
• Spectral Echoes: The shell designation suggests deep system integration—ensure the bin 
  field properly summons the CLI from any directory.

3. The Healing Rite (Concrete Code & Git Actions)
• Package.json Verification: Ensure description, license, and scripts are purified.
• Surgical Refactoring: Prioritize modularity and clear error propagation.

⚰️  Autopsy complete. May the deleted code rest in peace.
Enter fullscreen mode Exit fullscreen mode

2. haunted-shell exorcise <cmd>

Spawns any shell command inside an isolated execution chamber and captures real-time outputs.

  • If the command succeeds (exit code 0), it confirms the process was purified with no demons remaining.
  • If the command crashes (exit code != 0), it traps stderr, isolates the stack trace, and invokes Gemma 3:
    • The Curse Identified: A dramatic summary of what brought the process down.
    • The Forensic Breakdown: Exact technical root cause behind the stack trace.
    • The Banishing Incantation: The exact code patch or shell command to purge the defect.

Live Terminal Transcript: 

$ haunted-shell exorcise "node -e 'throw new ReferenceError(\"spectral_pointer is not defined\")'"

⚡ INITIATING TRIAL FOR COMMAND: node -e 'throw new ReferenceError("spectral_pointer is not defined")'
Executing in process chamber...


throw new ReferenceError("spectral_pointer is not defined")
^
ReferenceError: spectral_pointer is not defined
    at [eval]:1:7

────────────────────────────────────────────────────────────

⚡ CRASH DETECTED! A curse has possessed the process (Exit Code: 1).
Summoning spectral diagnosis from gemma3:4b...

1. The Curse Identified:
The spectral curse is one of unfulfilled expectation. The process sought to summon 
a variable—spectral_pointer—only to meet with a chilling silence in memory.

2. The Forensic Breakdown:
A ReferenceError was explicitly thrown during evaluation. The identifier was not
allocated in the lexical scope before execution.

3. The Banishing Incantation:
Declare the variable or wrap within a protective try/catch ward:

  try {
    invoke(spectral_pointer);
  } catch (e) {
    console.warn("The spirit was absent:", e.message);
  }

🔮 The exorcism rite concludes. Cast the incantation above to banish the error.
Enter fullscreen mode Exit fullscreen mode

3. haunted-shell seance

Opens an interactive, multi-turn readline REPL directly in your terminal. It pre-loads:

  • Active git branch & working tree status
  • Recent 5 commit logs
  • package.json scripts and metadata

It maintains conversation context across turns and includes built-in spectral shortcut rites (/status, /diff, /log, /clear, /exit).

Live Terminal Transcript: 

$ haunted-shell seance

🔮 THE CIRCLE IS CAST. COMMUNE WITH THE SPIRITS OF YOUR REPOSITORY.
   Branch: main | Tree: Working tree clean
   Recent Commits: 152ed19 feat: implement zero-dependency haunted-shell CLI for local open-weight AI

Special Rites: /help, /status, /diff, /log, /clear, /exit

👻 seance> What spirits haunt this repository?

The repository whispers of a nascent CLI medium, forged in the fires of 
Hacktoberfest Week 4. Its bloodline is pure Node.js ES modules, untainted by external 
dependencies. Yet I sense uncommitted diffs stirring beneath the surface...

👻 seance> /exit
🕯️ Blowing out the candles. The spirits return to the void.
Enter fullscreen mode Exit fullscreen mode

⚡ Architecture: Zero Dependencies

Haunted Shell requires zero npm packages. It is built entirely on modern Node.js 24 LTS native built-ins:

flowchart TD
    subgraph Terminal ["🖥️ Developer Terminal"]
        User["Developer"] -->|Command| CLI["haunted-shell (Node.js ES Module)"]
    end

    subgraph NativeNode ["⚙️ Native Node.js Built-ins (0 Dependencies)"]
        CLI --> NativeProc["node:child_process (spawn, execSync)"]
        CLI --> NativeRL["node:readline/promises (Interactive REPL)"]
        CLI --> NativeFetch["Global fetch + SSE Stream Reader"]
        CLI --> NativeColors["ANSI Spectral Palette (NO_COLOR safe)"]
    end

    subgraph GitTree ["📁 Local Git Repository"]
        NativeProc --> GitLog["git log -p (Deleted Code & Diffs)"]
        NativeProc --> GitStatus["git status & branch"]
        NativeProc --> ProcessChamber["Process Execution & Stderr Trap"]
    end

    subgraph LocalAI ["🧠 100% Offline Open-Weight Inference"]
        NativeFetch -->|/v1/chat/completions (OpenAI compatible)| Engine{"Local AI Provider"}
        Engine -->|Port 11434| Ollama["Ollama (gemma3:4b / qwen3:4b)"]
        Engine -->|Port 1234| LMStudio["LM Studio"]
    end
  • Global fetch + ReadableStream: Consumes Server-Sent Events (SSE) token-by-token directly from Ollama's /v1/chat/completions endpoint.
  • Native node:readline/promises: Powers the interactive seance REPL.
  • Native node:child_process: Safely traps stderr in a subprocess chamber without polluting the main shell.
  • ANSI Spectral Engine: Full terminal coloring with graceful degradation for non-TTY or NO_COLOR environments.

🛡️ Why Local Open-Weight Inference (Gemma 3) Matters

When building developer tools that inspect git histories and crash dumps, open innovation and local models are not just nice to have—they are essential:

  1. Absolute Privacy: Your git diffs, commit logs, and terminal crash traces contain proprietary intellectual property, internal file paths, and occasionally leaked tokens or credentials. With Gemma 3:4b running via Ollama, zero bytes ever leave localhost.
  2. 100% Offline Resilience: Development happens on flights, subways, remote trains, and off-grid locations. Haunted Shell works completely offline with the lights and internet turned off.
  3. Zero Token Billing: No API subscriptions, rate limits, or surprise bills from cloud AI providers.
  4. Permanent Ownership: The model is stored locally on disk. It cannot be deprecated, modified, or price-hiked by an upstream API vendor.

🤖 DevRelay Agent Session

The entire development and testing lifecycle of Haunted Shell—from initial zero-dependency architecture to live Gemma 3 streaming integration and commit diff forensic testing—was recorded using DevRelay:

Building Haunted Shell: Zero-Dependency Node.js CLI with Gemma 3 & Ollama
You

Create a zero-dependency Node.js ES module CLI for "haunted-shell" (Hacktoberfest Week 4: Ghost in the Machine) connecting to local open-weight models via Ollama (gemma3:4b) or LM Studio, supporting autopsy, exorcise, and seance.

Agent

Designed and implemented package.json, index.js, and README.md. Built native streaming SSE client, git diff and deleted-line extraction for 'autopsy', process chamber and stderr crash trapping for 'exorcise', and interactive readline REPL for 'seance'—all with 0 external dependencies using Node 24 built-ins.

You

Run autopsy and exorcise with local open-weight model Gemma 3:4b in Ollama.

Agent

Executed autopsy on the git commit tree and exorcised a failing Node.js eval command with Gemma 3:4b via Ollama. Gemma successfully delivered the in-character forensic breakdown, identified the curse, and provided banishing incantations.

4 of 4 messages

Direct Session Link: View full DevRelay Agent Session on DEV

🚀 Try It Yourself 

# 1. Pull Gemma 3 in Ollama
ollama run gemma3:4b

# 2. Clone and run Haunted Shell
git clone https://github.com/dhruv-gupta-dev/haunted-shell.git
cd haunted-shell
npm link

# 3. Commune with your repository
haunted-shell autopsy
haunted-shell exorcise npm test
haunted-shell seance
Enter fullscreen mode Exit fullscreen mode

May your deleted code rest in peace! 🕯️👻🕯️

Top comments (0)