GhostShell 讓終端幽靈在執行前解釋 Shell 命令並提示風險

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

What I Built

GhostShell is a haunted terminal companion. You type a shell command, and
before anything runs, a ghost explains it: what it does, where it came
from, and whether it is about to hurt you.

python -m ghostshell explain "ls -la"
python -m ghostshell explain "rm -rf /"
python -m ghostshell seance cobol "Who are you?"
python -m ghostshell --interactive

rm -rf / gets a critical warning and a refusal. ls -la gets a
murmur about a command that has watched directories fill and empty
since 1971. A seance lets you talk to the ghost of a dead programming
language — COBOL (1959), Fortran (1957), Pascal, APL, BASIC — on your
own machine, with no account and no cloud.

Demo

Run it with no model installed at all, and it still works:

👻  ghostshell whispers about: rm -rf /
    danger: critical
    lore:   rm (1971, early Unix): removes files.
    The ghost shudders. DO NOT RUN THIS as written.
    [dry-run: nothing was executed.]

With Ollama running locally, the same command is whispered by Gemma 3:

ollama pull gemma3
python -m ghostshell explain "grep -r TODO ."

Code

• Repository: https://github.com/AdjieC/ghostshell
• ghostshell/core.py — danger patterns, verified command lore, Ollama client, offline fallback
• ghostshell/cli.py — explain, seance, and the interactive REPL
• tests/test_core.py — 7 tests, all passing with the standard library only

Zero third-party dependencies. Python 3.10+.

How I Built It

Safety was the first design decision, not an afterthought. GhostShell
explains by default and never executes. Execution needs --execute
and an explicit y, and critical commands are refused outright.
Danger detection is rule-based and tested, not left to a model that
might miss rm -rf.

The model path is deliberately boring: a POST to localhost:11434
(Ollama), default model gemma3, overridable with GHOSTSHELL_MODEL.
The prompt hands the model only verified lore from a small table in
core.py. If a command is not in that table, the ghost says it does
not know its history, instead of inventing one. If Ollama is not
running, the rule engine answers instead. That fallback is the point.

Why Open Innovation Matters

A closed terminal assistant would send every command you type — your
file names, your servers, your mistakes — to someone else's server,
and stop working when that service changes price or shuts down.

GhostShell does the opposite. In offline mode your commands never leave
your machine; in Ollama mode they only go to localhost. You can swap
Gemma 3 for another open-weight model tomorrow without rewriting the
tool. It costs nothing to run, and it works with the internet off.
A ghost that needs the cloud is not a ghost. It is a subscription.

That is also why the project honours the past instead of just being
spooky: Unix commands from 1971, dead languages from 1959, and the
people who wrote them, are still here because their work was open
enough to survive them.

Prize Categories

• Best Use of Gemma: GhostShell's default local model is Gemma 3 via Ollama.