What I Built

Ghost Shell is a ghost that lives inside your terminal.

Every student remembers the first time a command failed and the error looked like a foreign language. Worse, beginners paste commands from the internet without understanding them, and one wrong rm -rf or git reset --hard can wipe out a whole project.

So I gave my terminal a ghost:

When a command fails, a spooky sound plays. Each mistake has its own sound: a creaky door for "command not found", rattling chains for "permission denied", a wail for a syntax error, footsteps for a missing file. The ghost then says a short spooky line and, under it, gives the real fix in plain words.

When a command is dangerous, the ghost stops it before it runs, explains what you would lose, and asks you to type yes to continue.

When you fix your mistake, a soft chime plays.

For example:

👻 The terminal graveyard echoes in silence... pythno has no soul in this realm.
Fix: Check for typos in pythno or install it via your package manager.

My take on the theme is a haunted machine that haunts you for your own good. The spooky layer is the fun part, but it never hides the answer, so a beginner learns something from every mistake.

Code

snehach03 / ghost_terminal

👻 Ghost Shell

::: {align="center"}

       .-.
      (o o) boo!
      | O \
       \   \
        `~~~'

A haunted terminal assistant for students.

:::

Ghost Shell is a lightweight terminal guardian designed to help students learn the command line without fear. It watches commands, explains common errors in plain English with a little spooky atmosphere, plays procedural sound effects, and checks potentially destructive commands against deterministic safety rules.

🛑 Dangerous-command checks: identifies configured destructive command patterns and explains the potential impact before execution.
🔊 Procedural sound effects: generates audio cues for errors, alerts, and successful fixes.
👻 Error explanations: combines spooky lore with a clearly labelled, actionable Fix: instruction.
⚡ Rule-first responses: common errors can be handled by built-in templates without calling an AI model.
🔒 Local-first design: everyday rule-based features work locally. An optional local model can be used as a fallback for unusual errors.

Note: Feature behaviour depends on the…

View on GitHub

How I Built It

Shell hooks for PowerShell, bash and zsh catch each command and its exit code, and check commands against the danger rules before they run.

Rules come first. Common errors (command not found, permission denied, file not found, syntax error) are explained instantly by built-in templates, so most mistakes never need an AI model.

Dangerous-command detection is rule-based on purpose. A pattern list covers rm -rf, git reset --hard, git clean -fd, git push --force, chmod -R 777, dd, mkfs, DROP DATABASE and fork bombs. I did not let a model decide what is dangerous, because a small model can misjudge risk and a pattern list cannot. A human always confirms before anything risky runs.

A small open-weight model handles the unusual cases. For long stack traces and unfamiliar tools, Ghost Shell asks Qwen2.5-0.5B-Instruct (a ~400 MB quantized GGUF file), served locally by llama.cpp's llama-server. The Python client calls it over localhost using only the standard library. If the server isn't running, the rule-based features keep working.

Sounds are generated with Python's built-in wave and math modules, so there are no licensing problems and no audio libraries. Users can swap in their own.

Explanations are cached, so a repeated error is instant.

I used Google AI Studio as my coding assistant to build the project from a detailed spec I wrote, then tested it myself.

I first considered Ollama, but it was too heavy for my laptop. Moving to llama.cpp with a tiny model, and letting rules do the routine work, made the tool lighter and faster, and I think it is a better design.

Why Does Open Innovation Matter?

Whatever a student types into a terminal can include file names, project names, and sometimes passwords or tokens by mistake. I didn't want any of that sent to a server.

It works offline. The ghost still haunts you with the Wi-Fi off, which suits a hostel or lab with bad internet.

Nothing you type leaves your machine. The model server runs on localhost, which wouldn't be true if explanations came from a closed API.

It costs nothing to run. No account, no API key, no per-request bill.

The model is swappable. Drop another GGUF model in the models/ folder and change one line in config.json, so the project isn't locked to a service that might change its pricing or disappear.

It runs on a plain laptop. A 0.5B model needs no GPU, so an ordinary student machine can use it.

DEV Community

Ghost Shell: The Terminal Ghost That Stops You From Wrecking Your Work