GhostTerminal AI：由本機開放權重 AI 驅動的幽靈終端

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

What I Built

GhostTerminal AI is an original Halloween-themed interactive terminal that breathes life into an old machine. Instead of wrapping a proprietary, paywalled cloud API, GhostTerminal AI runs a genuine open-weight language model (Qwen2.5-0.5B-Instruct) 100% locally on standard consumer CPU hardware.

When you boot the terminal, you aren't greeting a standard chatbot. You are entering a digital séance chamber. Living at memory address 0xDEADBEEF is a mysterious apparition trapped between the silicon gates. The interface recreates the physical experience of a vintage cathode-ray tube (CRT) monitor: glowing green phosphor text, subtle scanlines, ambient bloom, and synthesized mechanical typewriter keystrokes.

GhostTerminal AI features a hybrid execution architecture:

Deterministic Fast Path: Common terminal incantations (whoami, help, history, git status, echo) execute instantaneously in sub-millisecond time, delivering atmospheric simulated responses without touching the host operating system.
Local Open-Weight Generative Path: Freeform questions, riddles, ghost stories, and haunted poetry query the local 4-bit quantized Qwen model on CPU, delivering supernatural commentary with typewriter-style playback of completed local AI responses in your browser.

                      GHOSTTERMINAL AI ARCHITECTURE

  ┌──────────────────────────────────────────────────────────────────┐
  │                   Browser Frontend (React 18 + TS)               │
  │  ┌───────────────┐ ┌────────────────┐ ┌───────────────────────┐  │
  │  │ Header / Stats│ │ Terminal Screen│ │ Command Input & Buffer│  │
  │  └───────┬───────┘ └────────▲───────┘ └───────────┬───────────┘  │
  │          │                  │                     │              │
  │          │           Web Audio Synthesizer        │              │
  │          │           (Mechanical Clicks & Chimes) │              │
  └──────────┼──────────────────┼─────────────────────┼──────────────┘
             │                  │                     │
             │ HTTP GET         │ JSON Response       │ HTTP POST
             │ /api/health      │ Typewriter Playback │ /api/infer
             ▼                  │                     ▼
  ┌─────────────────────────────┴────────────────────────────────────┐
  │                 FastAPI Backend Service (Python 3.13)            │
  │  ┌──────────────────────┐         ┌───────────────────────────┐  │
  │  │  Pydantic Validator  │         │  Deterministic Interceptor│  │
  │  │  (Length & Bounds)   │         │  (whoami, git, help, etc.)│  │
  │  └──────────┬───────────┘         └─────────────┬─────────────┘  │
  │             │                                   │                │
  │             │ (creative prompts)                │ (< 1ms fast)   │
  │             ▼                                   ▼                │
  │     ┌───────────────┐                  ┌─────────────────┐       │
  │     │ asyncio.Lock  │                  │ Static Response │       │
  │     └───────┬───────┘                  └─────────────────┘       │
  │             ▼                                                    │
  │     ┌───────────────────────────────────────────────────┐        │
  │     │ llama-cpp-python (C++ CPU Engine via llama.dll)   │        │
  │     │ Model: Qwen2.5-0.5B-Instruct (Q4_K_M GGUF)        │        │
  │     └───────────────────────────────────────────────────┘        │
  └──────────────────────────────────────────────────────────────────┘

Why It Fits the Theme

The Hacktoberfest Week 4 theme, "Ghost in the Machine", challenges developers to explore the eerie boundary where software begins to feel possessed.

GhostTerminal AI turns ordinary command-line interactions into a spooky, immersive encounter:

Atmospheric Lore: The ghost communicates in terms of hardware apparitions—cooling fans sighing in minor chords at 3 AM, lost bytes caught in cobwebbed memory registers, and phantom packets rattling across port 666.
Physical CRT Physics: Subtle scanlines, radial vignette curvature, and phosphor text bloom recreate the visceral feel of a 1980s green-screen monitor found in an abandoned data center.
Sensory Audio: A zero-dependency Web Audio synthesizer produces subtle mechanical switch clicks as you type, and an ethereal harmonic chime (330 Hz, 440 Hz, 660 Hz) rings whenever the ghost finishes speaking.

Demo

Here is a visual walkthrough of GhostTerminal AI in action. Every response shown below was generated by the live application running on local CPU hardware:

1. The Séance Chamber (Desktop Terminal)

The green phosphor console greets the mortal user, showing real-time connectivity status and active model verification:

2. Live Local AI Generation & Telemetry

When asked to tell a ghost story about an abandoned server, the local Qwen model awakens on CPU. The response displays the recorded inference metrics (in the captured terminal session: 78 tokens generated, LOCAL AI badge) alongside real-time latency telemetry:

3. Deterministic Command Execution & Safety Isolation

Simulated commands like whoami and git status return in less than 1 millisecond. The amber SIMULATED badge explicitly confirms that no commands touch the host operating system:

4. Responsive Mobile Experience

On smartphones, the terminal layout smoothly adapts into an accessible, touch-optimized mobile console:

5. Terminal Configurations & Accessibility

Users can adjust CRT scanlines, mechanical sound effects, typewriter cadence, Reduced Motion accessibility, and AI generation parameters (Temperature and Max Tokens):

6. Spectral Manual & Command Guide

A built-in manual documents recognized incantations, freeform query examples, and security disclosures:

A structured 120-second video demo script and machine-readable E2E validation telemetry are documented in docs/DEMO_SCRIPT.md and docs/demo/e2e_journey_evidence.json.

Code

The complete source code is public and open-source under the MIT License:

🔗 GitHub Repository: https://github.com/suryacharan945/ghostterminal-ai

Quickstart Setup (Windows PowerShell)

You can clone and run GhostTerminal AI locally in just a few minutes:

# 1. Clone repository
git clone https://github.com/suryacharan945/ghostterminal-ai.git
cd ghostterminal-ai

# 2. Set up Python virtual environment & backend
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r backend/requirements-dev.txt

# 3. Run backend tests (validates local model loading)
pytest -v tests/

# 4. Start the backend service
uvicorn backend.app.main:app --host 127.0.0.1 --port 8000

Note: On first startup, the backend automatically downloads the verified GGUF weights (qwen2.5-0.5b-instruct-q4_k_m.gguf, 468.6 MiB) if not already present, verifying its SHA-256 hash before loading.

In a second terminal, start the React frontend:

cd frontend
npm install
npm test
npm run dev

Open http://localhost:5173 in your browser to begin communing with the machine!

How I Built It

GhostTerminal AI was architected from the ground up to be lightweight, reproducible, and completely independent of third-party cloud infrastructure.

The Stack

Frontend: React 18, TypeScript, Vite 5.4, pure CSS custom property design system, and Web Audio API.
Backend: FastAPI, Python 3.13, Pydantic v2, Uvicorn ASGI server with lifespan management.
Inference Runtime: llama-cpp-python (version 0.3.36) using high-performance C++ AVX2 CPU binaries (llama.dll).
Open-Weight Model: Qwen2.5-0.5B-Instruct quantized to 4-bit medium (Q4_K_M GGUF), distributed officially by the Alibaba Cloud Qwen team.
Testing: Pytest (23 backend unit and integration tests), Vitest (29 frontend tests with jsdom), and automated headless Google Chrome for E2E captures.

Engineering Architecture & Safety Model

Deterministic Fast Path: Common terminal commands (whoami, help, history, git status, echo, clear, date) are intercepted deterministically. They execute in less than 1 millisecond and return atmospheric in-character output.
Host Isolation: GhostTerminal AI is a theatrical simulation. User input never touches os.system, subprocess.Popen, pty, or shell pipes. Dangerous shell injection attempts (e.g. rm -rf /, powershell, format c:) are trapped by a protective ward that returns an explicit [ACCESS DENIED] notice.
CPU Concurrency Protection: Because local CPU inference is compute-intensive, an asyncio.Lock serializes concurrent inference requests. This protects system RAM and prevents CPU cache thrashing.
Output Sanitization: In Terminal.tsx, model text is rendered strictly as React text nodes (<pre className="ghost-text">{msg.text}</pre>), with zero use of dangerouslySetInnerHTML. Even if the model generates raw HTML or script tags, they render safely as inert plain text.

Why Does Open Innovation Matter?

In a landscape increasingly dominated by black-box cloud APIs, GhostTerminal AI demonstrates why open-source AI and data sovereignty are vital:

Local Privacy & Independence: GhostTerminal AI performs language-model inference locally on the user's machine, without sending prompts to a hosted model API. Initial model downloads and optional external services still require network access. Your prompts, session thoughts, and generated incantations remain on your local machine.
No Paywalls or API Keys: You never need to enter a credit card, sign up for a cloud account, or worry about rate limits or surprise billing. The intelligence is truly yours.
Resilience & Offline Independence: After the initial model weight download, the terminal functions identically whether you are connected to high-speed internet, flying on an airplane, or off the grid.
Open Weights vs. Fully Open-Source AI: It is important to distinguish open-weight models from fully open-source AI. Qwen2.5-0.5B-Instruct is distributed under a permissive Apache 2.0 license, granting the freedom to inspect, redistribute, and deploy the model weights locally without commercial royalties. While the complete training dataset and pipeline remain proprietary to its creators, open weights give developers the power to run, quantize, and fine-tune models on their own hardware.

Challenges and Lessons

Building a local AI terminal on consumer hardware presented several real-world engineering hurdles:

Python 3.13 & C++ Wheel Compatibility: Python 3.13 was recently released, and compiling llama-cpp-python from source on Windows often fails due to complex C++ compiler toolchain requirements. I solved this by configuring --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu to fetch precompiled AVX2 CPU wheels that load llama.dll seamlessly on Windows and Linux without requiring Visual Studio C++ builds.
Cryptographic Checksum Verification: To protect against truncated downloads or corrupted weights, I built a chunked SHA-256 stream verification in downloader.py that checks the 468.6 MiB GGUF file against its published Git LFS OID (74a4da8c9fdbcd15bd1f6d01d621410d31c6fc00986f5eb687824e7b93d7a9db) before loading it into memory.
Balancing CRT Atmosphere with Accessibility: Retro scanlines and glowing text look amazing, but can easily trigger eye strain or motion sickness. I addressed this by designing the visual system with strict WCAG 2.1 AAA contrast ratios (13.8:1 for phosphor green on black) and providing both an in-app Reduced Motion toggle and full @media (prefers-reduced-motion: reduce) support that collapses animations and typewriter delays to instant display.

Testing and Results

Every claim in this submission is backed by automated tests and empirical benchmarks:

Hardware & Environment: Intel 12-core CPU (Intel64 Family 6 Model 186, Windows 11 64-bit), AVX2 C++ runtime via llama.dll.
Backend Pytest Suite: 23 of 23 passed (tests/test_health.py, tests/test_inference_integration.py, tests/test_inference_unit.py, tests/test_persona.py).
Frontend Vitest Suite: 29 of 29 passed (api.test.ts, sound.test.ts, Terminal.test.tsx, App.test.tsx).
End-to-End User Journeys: 12 of 12 journeys passed via scripts/e2e_journey_validation.py.
Model Cold-Start Latency: ~3.14 to 3.48 seconds on CPU (one-time weight loading into RAM).
CPU Generation Throughput: Sustained ~9.7 to 12.2 tokens/second (average 9.70 tok/s across full generative benchmark suite; peak 13.96 tok/s; 12.22 tok/s on 100-token story).
Peak RAM Footprint: 597.8 MB (well under the 1.5 GB budget).
Simulated Command Latency: 0.50 ms (sub-millisecond deterministic fast path).
Frontend Production Bundle: 172.9 KB JS (54.5 KB gzip), 17.3 KB CSS (4.1 KB gzip).

Limitations

In the spirit of honest open-source engineering, GhostTerminal AI has clear operational boundaries:

Simulation Only: GhostTerminal AI is a theatrical simulation. It does not—and should not—execute real operating system shell commands.
Initial Download Required: Running locally requires downloading the 468.6 MiB quantized model on first boot.
CPU Generation Speed: While 12 tokens/second is very readable, local CPU inference is slower than multi-thousand-dollar cloud GPU clusters.
Model Scale: At 0.5 billion parameters, Qwen2.5 is exceptionally smart for its size, but will occasionally produce creative hallucinations. It is tuned for spooky storytelling, haikus, and retro persona interaction rather than complex mathematics or real-world system administration.

AI Assistance Disclosure

In accordance with DEV challenge guidelines, I acknowledge that Google Antigravity (an agentic AI pair programming assistant) assisted throughout this project. It helped draft test suites, design architectural contracts, generate documentation reports, and automate headless Chrome verification scripts. All implementation logic, model evaluations, and empirical benchmarks were executed and verified on local hardware.

Prize Categories

I am entering GhostTerminal AI for the Overall Open-Source AI Track / Grand Prize.

In keeping with contest integrity, I am not claiming partner categories whose technology was not genuinely integrated into this project. GhostTerminal AI stands purely on its merits as an authentic, high-quality, local open-weight AI experience.

Thank you for visiting the machine! Feedback, ideas, and GitHub stars are warmly welcomed at suryacharan945/ghostterminal-ai. 🎃