ELKADY

Posted on Oct 30 Edited on Oct 30 Originally published at dev.to

GhostTerm: The Haunted Terminal Companion Powered by Local Gemma 2 👻

#devchallenge #hf26challenge #gemma #ai

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

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

     .-.
    (o o)       G H O S T T E R M
    | O \       The Spirit in the Machine
     \   \      Hacktoberfest 2026 • DEV Challenge Week 4
      `~~~'     Local Gemma 2 Necromancy Engine

"Every codebase is a cemetery of forgotten decisions. GhostTerm gives the dead a voice."

What I Built

Every software engineer knows the cold, existential dread of staring at a terminal at 2:43 AM. A crucial build script dies with a silent Exit code 1. A mysterious TypeError: 'NoneType' object is not subscriptable appears in a microservice. Or worse, you open a legacy repository and discover a comment left four years ago by an engineer who long vanished:

# FIXME: DO NOT TOUCH THIS UNDER ANY CIRCUMSTANCES.
# God only knows why this prevents the payment engine from deadlocking.

I built GhostTerm (or NecroShell): a lightweight, eerie, production-ready terminal companion and process wrapper designed to banish silent graveyard bugs forever.

Instead of dry, unhelpful error dumps, GhostTerm turns developer debugging into an atmospheric gothic séance. Running as a fast interactive CLI wrapper, it watches your commands, intercepts crashed processes, exhumes the repo’s git graveyard, and channels Google DeepMind's open-weight Gemma 2 model running 100% locally via Ollama to whisper haunted diagnostics, forensic post-mortems, and actionable resurrection fixes.

Key Capabilities:

👁 Process Haunting (haunt <cmd>): Transparently executes any developer command (python, npm, cargo, docker, git). If the process dies, GhostTerm conducts an immediate forensic autopsy, extracting the fatal stack frames and channeling Gemma 2 to prescribe the exact exorcism incantation (fix).
🔮 Haunted Index Calculator (index): Mathematically evaluates your codebase’s supernatural entropy on a scale from 1% to 100%, scoring uncommitted ghost files, cursed comment runes (TODO, FIXME, HACK, WTF, DEBT), necrotic monolith files (>400 lines), and late-night panic commits.
⚰ Git Graveyard Exhumation (exhume): Unearths the cemetery of past commits, flagging frantic commit messages, abandoned hotfixes, and suspicious "Witching Hour" commits authored between 1:00 AM and 5:00 AM.
🕯 Interactive Séance (seance): A live terminal altar where developers can converse directly with the trapped compiler spirit about tricky architectural trade-offs, cryptic segfaults, or existential debugging dread.
⚡ Offline Spectral Grimoire: If Ollama is sleeping or you're coding without Wi-Fi, GhostTerm never throws unhandled network errors—it automatically falls back to an offline heuristic grimoire covering 30+ classical programming errors.

Demo

Here is GhostTerm in action across common developer workflows with actual terminal captures.

1. Haunting a Fatal Process (`ghost_term haunt python script.py`)

When a process crashes with an unhandled exception, GhostTerm catches the exit code, displays a spectral tombstone, and delivers an immediate autopsy:

┌─────────────────────────── 💀 GHOSTTERMD ACTIVE ────────────────────────────┐
│ 👁 Possessing command: python examples/cursed_script.py                      │
│ Spirits watch the standard descriptors...                                   │
└─────────────────────────────────────────────────────────────────────────────┘
[*] Initiating mortal computation ritual...
[*] Attempting to partition reality by zero...
ZeroDivisionError: division by zero

          _______
         /  R.I.P \
        /  EXIT 1 \
       |-----------|
       |  DECEASED |
       |  PROCESS  |
       |___________|

╔══════════════════════════ ☠ POST-MORTEM AUTOPSY ☠ ══════════════════════════╗
║ 💀 Fatal Anomaly: The singularity opens: dividing by pure nothingness       ║
║                                                                             ║
║ 📜 Post-Mortem Forensic:                                                    ║
║ Mathematics collapsed when an equation attempted to partition reality by    ║
║ zero.                                                                       ║
║                                                                             ║
║ 🔮 Exorcism & Resurrection:                                                 ║
║ Add a protective talisman: `if divisor != 0:` to prevent catastrophic       ║
║ collapse.                                                                   ║
║                                                                             ║
║ ✦ Channel: Eldritch Grimoire (Offline Heuristic Engine)                     ║
╚═══════════════════════ Exit Code 1 • Duration 0.62s ════════════════════════╝

2. Measuring Repository Supernatural Entropy (`ghost_term index`)

GhostTerm audits the repository's git health, cursed comments, and necrotic monoliths to calculate a quantitative Haunted Index (1% - 100%):

┌─────────────────────── 🔮 SYSTEM HAUNTED INDEX AUDIT ───────────────────────┐
│ Scanning code catacombs at: /workspace/GhostTerm                            │
│ Detecting technical decay, forgotten promises, and uncommitted phantoms...  │
└─────────────────────────────────────────────────────────────────────────────┘

                     Entropy & Dread Diagnostic Breakdown                      
┌───────────────────┬─────────────────────────┬────────────┬──────────────────┐
│ Dread Dimension   │ Observed Anomaly        │Curse Score │ Verdict          │
├───────────────────┼─────────────────────────┼────────────┼──────────────────┤
│ Uncommitted Souls │ 6 uncommitted file(s)   │       +18% │ Files in limbo   │
│ Cursed Runes      │ 37 dark runes (TODO)    │       +30% │ Unkept promises  │
│ Despair in Git    │ 0 frantic fix commits   │        +0% │ Tranquil history │
│ Necrotic Monoliths│ 1 monolithic crypt file │        +5% │ Logic catacombs  │
└───────────────────┴─────────────────────────┴────────────┴──────────────────┘

╔═══════════════════════ 🕯 SPECTRAL ASSESSMENT: 53% 🕯 ════════════════════════╗
║ HAUNTED INDEX: 53%                                                          ║
║ Grave Meter: [█████████████████████░░░░░░░░░░░░░░░░░░░] 53/100              ║
║                                                                             ║
║ Threat Classification: HAUNTED GROVE (Active Supernatural Murmurs)          ║
║ Prescribed Ward: TODO markers and uncommitted changes are gathering         ║
║ strength. Cleanse them before the next moon.                                ║
╚═════════════════════════════════════════════════════════════════════════════╝

3. Exhuming the Git Graveyard (`ghost_term exhume`)

Unearths the history of past commits, broken branches, and witching-hour coding rituals:

4. Interactive Séance with the Machine Spirit (`ghost_term seance`)

Developers can summon the spirit to analyze architectural decisions or cryptic runtime anomalies:

5. Direct Crash Dump & Log Autopsy (`ghost_term autopsy <file>`)

Directly parses server logs, crash dumps, or core backtraces without rerunning the failure:

Code

The complete source code is open source and available on GitHub:

👉 GitHub: kady-x/GhostTerm (MIT Licensed)

Installation in 30 Seconds:

git clone https://github.com/kady-x/GhostTerm.git
cd GhostTerm
pip install -r requirements.txt
python ghost_term.py --help

How I Built It

GhostTerm was built with a strict focus on minimalism, speed, and privacy.

System Architecture

 +-------------------------------------------------------------------------+
 |                              DEVELOPER CLI                              |
 |     $ python ghost_term.py haunt python script.py                       |
 +-------------------------------------------------------------------------+
                                      │
                                      ▼
 +-------------------------------------------------------------------------+
 |                           GHOSTTERM ORCHESTRATOR                        |
 |  - Subprocess Life Cycle Interceptor                                    |
 |  - Git Graveyard & Cursed Rune Scanner                                  |
 |  - Spooky Rich Palette (#00f0ff Cyan, #bd93f9 Purple, #ff5555 Blood)   |
 +-------------------------------------------------------------------------+
                                      │
                    ┌─────────────────┴─────────────────┐
                    │                                   │
         [Ollama Online]                      [Ollama Offline]
                    │                                   │
                    ▼                                   ▼
 +------------------------------------+  +--------------------------------+
 |     LOCAL GEMMA 2 (via Ollama)     |  |    ELDRITCH HEURISTIC GRIMOIRE |
 |   - Model: gemma2:2b / gemma2:9b   |  |  - 30+ Stack Trace Patterns    |
 |   - 100% Offline & On-Device       |  |  - Zero Network Dependencies   |
 |   - Zero Token Telemetry           |  |  - Instantaneous Determinism   |
 |   - Victorian Compiler Personality |  |  - Gothic Remedy Formulations  |
 +------------------------------------+  +--------------------------------+
                    │                                   │
                    └─────────────────┬─────────────────┘
                                      │
                                      ▼
 +-------------------------------------------------------------------------+
 |                         RICH SPECTRAL INTERFACE                         |
 |  - Terminal Tombstone Graphics (ASCII R.I.P banners)                    |
 |  - Diagnostic Threat Breakdown Tables                                   |
 |  - Atmospheric Actionable Resurrection Wards                            |
 +-------------------------------------------------------------------------+

1. The Dual-Engine Intelligence Strategy

Developer CLI tools must never hang, crash, or fail when network connectivity drops. GhostTerm implements a resilient two-tier intelligence engine:

Primary Tier (Gemma 2 via Ollama): Queries a local instance of Google DeepMind's gemma2:2b or gemma2:9b. A carefully structured system prompt instructs Gemma to adopt the persona of a Victorian/eldritch compiler spirit—delivering atmospheric prose followed by strictly accurate technical solutions.
Secondary Tier (Eldritch Heuristic Grimoire): If Ollama is offline, GhostTerm intercepts the connection error within milliseconds and activates an embedded grimoire. With pattern-matching regexes covering syntax errors, indentation traps, null pointers, module resolution errors, recursion spirals, segmentation faults, and git merge conflicts, developers get witty, helpful post-mortems even on an airplane.

2. Subprocess Life-Cycle Possession

GhostTerm’s haunt command acts as a non-invasive wrapper. It launches commands via subprocess.Popen, transparently proxying stdout and stderr in real-time. Only when the exit code signals death (returncode != 0) does GhostTerm step in to perform its forensic autopsy, extracting the last 800 characters of the fatal stack trace and submitting it for immediate diagnostic analysis.

3. Quantitative Supernatural Entropy

The HauntedIndexScanner parses the local workspace across four dimensions:

Uncommitted Git Drift: Untracked and uncommitted files lingering in limbo (git status --porcelain).
Cursed Source Runes: Multi-language regex scanning across .py, .js, .ts, .rs, .go, .cpp, .c for debt markers (TODO, FIXME, HACK, WTF, BUG, DEPRECATED).
Git Despair Sentiment: Semantic frequency analysis across recent commits for panic tokens (fix, wip, broken, revert, undo, help).
Necrotic Monolith Files: Source files exceeding 400 lines that haven't been decomposed.

4. Rich Terminal Aesthetics

Terminal styling is powered by the Python rich library with custom hex palettes:

Spectral Cyan (#00f0ff): Active prompts and live executions.
Phantom Purple (#bd93f9): Scroll borders and necromantic headings.
Blood Orange (#ff5555): Fatal tombstones and catastrophic errors.
Ectoplasm Green (#50fa7b): Clean executions and healing blessings.

Why Does Open Innovation Matter?

In the current era of proprietary AI, developers are frequently encouraged to pipe terminal commands and codebase context into third-party cloud APIs. For developer tooling, this is an immense security and privacy hazard.

The terminal is the most confidential surface on any developer's machine:

Sensitive Credentials: Stack traces regularly dump unmasked API keys, OAuth bearer tokens, and JWT claims.
Infrastructure Architecture: Error backtraces reveal internal IP addresses, microservice names, and database connection strings.
Intellectual Property: Proprietary algorithms, unreleased features, and patented logic reside directly inside stack frames and git diffs.

Open innovation and open-weight models like Gemma 2 change the paradigm completely.

By utilizing Gemma 2:

Zero Data Leakage: Not a single character leaves the developer's laptop. All inference happens locally in GPU/CPU VRAM.
Offline Sovereignty: Developers can debug systems in secure air-gapped environments, on airplanes, or inside corporate firewalls without third-party API dependencies.
No Per-Token Metering: Developers can analyze thousands of lines of logs, git histories, and tests without fear of monthly API bills.

Open-weight models empower developers to build truly personal, private, and permanent developer tooling.

Prize Categories

Category: Best Use of Gemma

GhostTerm is built from the ground up to showcase the unique strengths of Google DeepMind's Gemma 2:

Compact Reasoning Power: gemma2:2b runs effortlessly on consumer laptops while providing nuanced, atmospheric roleplay combined with razor-sharp code debugging.
Structured Instruction Adherence: Gemma 2 reliably formats complex outputs into structured post-mortem sections (Curse Title, Forensic Autopsy, Exorcism Spell) without breaking CLI parsing.
Local-First Privacy: Demonstrates how Gemma 2 enables developer tooling that respects zero-trust security and complete data sovereignty.

Authored by @kadyx (GitHub @kady-x)

Awaken your terminal from the dead. May your builds compile, your tests pass, and your silicon spirits rest in peace. 👻

Top comments (1)

Alex Shev • Oct 30

A local terminal assistant earns trust when its proposals are reversible and inspectable. Showing the exact command, the assumed working directory, and the expected changed files before execution turns a fun interface into something developers can safely use on a real repository.