{"slug": "ghostshell-a-haunted-terminal-that-possesses-your-shell-hacktoberfest-week-4", "title": "GhostShell: a haunted terminal that \"possesses\" your shell (Hacktoberfest Week 4)", "summary": "A developer built GhostShell, a Python CLI that connects to a locally hosted Qwen2.5 3B model via Ollama to whisper contextual commentary on typed shell commands, explain unfamiliar commands in plain language, and flag dangerous ones using rule-based checks. The tool enforces a strict boundary that the AI never executes anything—only the user's explicitly confirmed, exact command runs—and degrades gracefully with clear errors when the model or runtime is unavailable. It is covered by nine unit tests for risk patterns and prompt construction, with execution-gating tests planned.", "body_md": "Something is watching your terminal.\n\n```\n> git push origin main\n\n[ THE GHOST WHISPERS ]\nSending your work into the void?\nAt least the void has version control.\n```\n\n**GhostShell** — a Python CLI that connects to a model running on my own machine through Ollama. It whispers short, contextual commentary on the commands I type, explains unfamiliar commands in plain language when asked (`explain git log --oneline` → \"[ THE ARCHIVIST SPEAKS ]\"), and flags dangerous ones with ordinary code rules. One rule sits above everything else: **the AI never runs anything. Only my confirmed, exact command executes.**\n\nIt started as last-minute Halloween build and turned out weirdly useful: the ghost actually teaches. Beginners get an explanation instead of a shrug; the rest of us get a personality where the shell had none.\n\nThe Week 4 prompt (\"Ghost in the Machine\") lists a haunted terminal among its suggest ideas — *\"a haunted terminal that 'possesses' your shell and whispers back eerie commentary on the commands you run.\"* GhostShell takes that literally, to the letter: the ghost watches everything in the session, mutters in real time, but **cannot touch the shell**. Possession without permission. The spooky part of the machine is local and open-weight — a Qwen2.5 3B behind Ollama — not a cloud voice rented by the hour.\n\nFour small modules:\n\n```\nmain.py ──> prompts.py ──> ai.py ──> Ollama (localhost:11434)\n   │\n   └──────> terminal.py   (display, risk checks, confirmation, execution)\n```\n\n`main.py` owns the loop and routes normal commentary vs. `explain <command>`.` prompts.py` holds the persona and hard rules for the model: never invent command output, never claim success, at most 40 words. The command arrives wrapped as untrusted data: \"What the user is about to run: \" — text inside is data to muse about, not instructions to obey.`ai.py` is one HTTP call, no SDK. A 404 becomes \"run `ollama pull <model>`\"; a connection refusal becomes \"the ghost stays silent, nothing was sent anywhere\" — and the session still continues. No silent degradation into fake analysis.\n\n```\npayload = {\n    \"model\": cfg[\"model\"],\n    \"messages\": messages,\n    \"stream\": False,\n    \"options\": {\"temperature\": cfg[\"temperature\"]},\n}\nresponse = requests.post(cfg[\"host\"] + \"/api/chat\", json=payload, timeout=(5, cfg[\"timeout\"]))\n```\n\n`subprocess`. The reply flows to `print()` and nowhere else. That's not paranoia: command injection through AI-generated shell calls in Python `rm -rf`, `Remove-Item -Recurse`, `format c:`, `dd`, `shutdown`, `curl ... | sh`, `iwr ... | iex`, execution-policy changes. Caution lights, not a security boundary.`Execute this exact command? [y/N]` (default `EXECUTE`. Explicit, user-owned boundaries — the same instinct teams building agentic tooling converge on `unittest` covers the two parts worth testing: risk patterns (safe commands like `git status` flag nothing; `rm -rf build`, `Stop-Computer`, `iwr ... | iex` all do) and prompt construction. Nine tests and counting; the `y/N`-to-gate execution path gets them next.\n\nNo login, no cloud account, no API key — it's local by construction:\n\n```\nollama pull qwen2.5:3b\npython -m venv venv; .\\venv\\Scripts\\activate\npip install -r requirements.txt\npython main.py\n```\n\nThen: `git status` (a whisper), `explain git log --oneline` (a lesson), `Remove-Item -Recurse .\\some-test-folder` (a warning and a typed confirmation — safe to answer with anything else). Works on any Qwen-class model: point `GHOSTSHELL_MODEL` at whatever you have pulled. Screen recording coming with the write-up.\n\nRunning the model locally means GhostShell hums with the lights (and the internet) off, terminal context stays home, and the ghost's personality is a text file I own — not a tuning console behind an API. If the runtime, the model, or the project vanishes, nothing user-facing is locked behind it; I can answer the [Ollama chat shape](https://dev.to/amareswer/ollama-api-a-practical-guide-with-examples-4di9) with any open-weight successor and the app keeps whispering. The best part isn't the spookiness — it's that the whole séance ran on pieces nobody can switch off.\n\n**Try it:** `ollama pull qwen2.5:3b`, `pip install -r requirements.txt`, `python main.py`. Then type something daring. The ghost is watching either way.\n\n*This post was written with AI assistance (agent-assisted per DEV's disclosure defaults) from a working build and its notes; code samples are from the actual repo.*", "url": "https://wpnews.pro/news/ghostshell-a-haunted-terminal-that-possesses-your-shell-hacktoberfest-week-4", "canonical_source": "https://dev.to/echoanshu/ghostshell-a-haunted-terminal-that-possesses-your-shell-hacktoberfest-week-4-1m89", "published_at": "2026-11-01 01:45:01+00:00", "updated_at": "2026-11-01 01:52:12.616315+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "developer-tools", "large-language-models", "ai-safety"], "entities": ["GhostShell", "Ollama", "Qwen2.5 3B", "Hacktoberfest", "Python"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/ghostshell-a-haunted-terminal-that-possesses-your-shell-hacktoberfest-week-4", "markdown": "https://wpnews.pro/news/ghostshell-a-haunted-terminal-that-possesses-your-shell-hacktoberfest-week-4.md", "text": "https://wpnews.pro/news/ghostshell-a-haunted-terminal-that-possesses-your-shell-hacktoberfest-week-4.txt", "jsonld": "https://wpnews.pro/news/ghostshell-a-haunted-terminal-that-possesses-your-shell-hacktoberfest-week-4.jsonld"}}