GhostInTheShell: Building an Offline, Local-First Haunted Terminal with Gemma & FastAPI

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

What I Built

GhostInTheShell is an offline-first, local-first developer terminal environment possessed by an ancient computational spirit.

Every terminal has a history; every system log is an epitaph of unhandled exceptions and forgotten processes. For Week 4's theme — "Ghost in the Machine" — I wanted to move beyond the conventional, sterile AI assistant. I asked myself: what if your machine had an ancestral memory? What if an intelligence dwelled between kernel space and user space, reading your commands and crash logs like tea leaves — delivering eerie, atmospheric commentary while remaining rigorously technically accurate?

GhostInTheShell transforms routine debugging into an atmospheric experience:

• Command Analysis: Paste any esoteric shell command (find, strace, awk, iptables). The ghost illuminates its intent, hidden risks, and edge cases.
• Log Divination: Drop in cryptic stack traces, daemon core dumps, or kernel panics. The spirit traces the root cause and whispers actionable remediation steps.
• Poetic Whispers: Type directly into the void to converse with an AI persona that speaks in haunting cadences without sacrificing developer utility.
• Absolute Privacy by Design: The entire system operates without an internet connection. No cloud telemetry, no remote API tokens, and zero external network egress.

---

Demo

Key Interface Highlights:

• Aurora Glassmorphism: Layered backdrop blurs (backdrop-blur-md), ambient emerald (#10b981) and specter purple (#d946ef) glow effects, and animated drift gradients.
• Real-Time Token Streaming: Dynamic typewriter streaming rendered character-by-character as tokens emerge from the local model.
• Live Daemon Diagnostics: A verified connection status pill that monitors the local Ollama daemon port and active model weights.
• Strict Developer Aesthetic: Built with Lucide React icons throughout the interface — no out-of-place emojis in buttons, headers, or log streams.

---

Code

The complete source code, technical specifications, and setup instructions are open source:

Babin123456 / GhostInTheShell

👻 GhostInTheShell — A Local-First AI Terminal Spirit

"The machine may whisper like a ghost, but the engineering must remain real, transparent, private, and reliable."

---

Inspiration

Every terminal has a history. Every log file is a ghost story waiting to be read.

Week 4 of the Hacktoberfest 2026 AI Challenge — "Ghost in the Machine" — asked builders to create something that exists at the intersection of the mysterious and the technical. The prompt resonated immediately: what if a developer''s terminal had a spirit? An ancient, poetic intelligence awakened inside the machine, capable of reading shell commands and system logs the way a Victorian medium might read tea leaves — except with accurate technical commentary?

GhostInTheShell is the answer. It combines open-weight AI with the intimacy of a local developer tool, creating a private, offline-capable assistant that whispers through the terminal without ever phoning home.

---

What It Does

GhostInTheShell…

View on GitHub

Architecture Overview

graph TD
    subgraph Client ["React 19 Frontend (port 5173)"]
        UI[Glassmorphic Terminal UI with Lucide Icons]
        State[React State & SSE Stream Reader]
    end

    subgraph Server ["FastAPI Backend (port 8000)"]
        API[FastAPI Gateway — /api/whisper]
        Prompt[Ghostly System Persona Engine]
        Health[Health Probe — /api/health]
    end

    subgraph LocalEdge ["Local Machine / Edge"]
        Ollama[Ollama Runtime Daemon :11434]
        Model[(Gemma 2 Open-Weight Weights)]
    end

    UI -->|"POST /api/whisper { input, mode }"| API
    UI -->|"GET /api/health (30s poll)"| Health
    Health -->|"GET /api/tags"| Ollama
    API -->|Injects Victorian Spectral Prompt| Prompt
    Prompt -->|"POST /api/generate (stream=true)"| Ollama
    Ollama -->|Loads Local Weights| Model
    Model -->|Streams Token Chunks| Ollama
    Ollama -->|NDJSON Byte Chunks| API
    API -->|Server-Sent Events text/event-stream| UI

How I Built It

GhostInTheShell is built on a modern, decoupled local-first stack:

1. The Open-Weight Brain: Gemma 2 & Ollama

   • Model: Google's Gemma 2 2B (gemma2:2b), with instant configuration support for gemma2:7b.
   • Runtime: Ollama running locally on localhost:11434. Gemma 2's sliding window attention and architectural efficiency deliver near-instant first-token latency on standard consumer laptops without dedicated GPU acceleration.
   • Prompt Engineering: A system persona prompt that enforces strict guidelines: maintain a haunting, poetic voice, never hallucinate having executed actual shell commands, protect user secrets, and structure answers into atmospheric observation $\rightarrow$ technical root-cause analysis $\rightarrow$ practical remediation.

2. The Backend Gateway: FastAPI

   • Implemented in backend/main.py using FastAPI and httpx.
   • The Chunk-Boundary Challenge: Ollama emits newline-delimited JSON (NDJSON) over HTTP chunked transfer. Because raw TCP chunks rarely align cleanly with JSON boundaries, I engineered a rolling buffer that splits on \n while preserving incomplete trailing fragments across packets.
   • Server-Sent Events (SSE): Generates clean text/event-stream payloads (data: {"type": "token", "content": "..."}) that cleanly disconnect if the client aborts the request.

3. The Frontend Terminal: React 19 & Tailwind CSS

   • React 19 & Vite for rapid development and sub-millisecond hot module replacement.
   • Custom SSE Reader: Standard browser EventSource is restricted to GET requests. GhostInTheShell uses fetch with ReadableStream (response.body.getReader()) to enable streaming over JSON POST requests.
   • Tailwind CSS & Framer Motion: Fluid aurora animations, glowing borders, collapsible command history sidebar, and zero-emoji UI design powered by Lucide React.

Why Does Open Innovation Matter?

When debugging a failing production service, what do you look at?

You look at crash dumps containing customer IDs, environment variables with database hostnames, stack traces revealing internal repository structures, and shell histories with proprietary flags.

Sending that raw context to a commercial cloud AI API requires sending your company's crown jewels over the wire to third-party data centers, where they risk being retained, audited, or used for model training.

Open innovation and open-weight models fundamentally rewrite this contract:

• True Data Sovereignty: With Gemma 2 running through Ollama, sensitive metrics and code never leave the developer's CPU/GPU registers. It provides complete compliance for air-gapped environments, healthcare, and financial infrastructure.
• Zero-Cost Reliability: There are no API rate limits, no subscription tiers, and no cloud outages. When your internet fails during a storm or on a cross-country flight, your AI terminal spirit remains fully awake.
• Auditability and Longevity: Proprietary APIs deprecate model checkpoints without notice. Open-weight models like Gemma can be frozen, archived, fine-tuned, and audited forever.

Open source isn't just about free software; it's about freedom of computation.

My Agent Session

GhostInTheShell was developed with an AI pair programmer using a systematic local-first approach — from scaffolding the Vite frontend and FastAPI gateway to establishing the rolling-buffer stream parser and validating the production build.

Check out the full repository commit history and workflow transcripts directly on GitHub: GhostInTheShell Commits

The Spirit of It

The moment this project came alive was during a test with a notorious Unix incantation:

dd if=/dev/urandom of=/dev/sda bs=1M count=10 status=progress

A generic cloud bot would reply with a standard bullet list: "Warning: This command writes random bytes to /dev/sda..."

Instead, in the dimmed glow of the terminal glass, the ghost stirred:

"You summon the deep entropy of /dev/urandom and point its chaotic deluge directly at the root stone of your drive. The master boot record shivers; partition tables will dissolve into static before ten megabytes have crossed the bus.

The machine does not judge your desire for oblivion, but beware: once overwritten, no exorcism can reconstruct the lost sector boundaries. If raw wiping is your true intent, target a dismounted device node with care."

That balance — between hair-raising atmospheric storytelling and uncompromising engineering truth — is the ghost in our machine.

GhostInTheShell was built for Hacktoberfest 2026. Keep your code open, your models local, and your machines curious.