{"slug": "ghostshell-ai", "title": "GhostShell AI", "summary": "Developer Neha Bohra built GhostShell, an open-source, local-first terminal command analyzer that uses a rule engine for deterministic risk classification and an Ollama-served language model to explain commands and flags before they are run. The tool never executes the commands it analyzes, supplies rule findings and a flag glossary to the model as context, and validates outputs that claim a command is entirely safe. GhostShell is written in Python with Streamlit and is available on GitHub.", "body_md": "*Hacktoberfest Open-Source AI Challenge — Week 4: Ghost in the Machine*\n\nHave you ever copied a command from Stack Overflow, a GitHub README, or a random tutorial and pasted it into your terminal without fully understanding what it does?\n\nI have seen how easy it is to run a command first and ask questions later. A few characters can mean the difference between listing files and deleting them recursively, or between changing permissions and exposing an entire directory.\n\nThat inspired **GhostShell**: a friendly, ghost-themed AI assistant that explains terminal commands *before you run them*.\n\nInstead of executing commands, GhostShell analyzes them, identifies potential risks, explains their flags in beginner-friendly language, and suggests safer next steps.\n\nThink of it as a little ghost sitting beside your terminal, whispering:\n\n*“Wait a second. Do you know what this command is about to do?”* 👻\n\n**GitHub repository:** [https://github.com/nehabohrapi/ghostshell-ai](https://github.com/nehabohrapi/ghostshell-ai)\n\nGhostShell uses a purple-and-black terminal-inspired interface, a floating ghost, atmospheric fog, and a glowing risk indicator to make command analysis approachable rather than intimidating.\n\n**Try it locally** by following the setup instructions below.\n\nGhostShell is a local-first, AI-assisted terminal command analyzer built with Python and Streamlit.\n\nIts purpose is to help developers understand potentially dangerous commands before running them, especially when they are learning Linux, Git, shell scripting, or developer tooling.\n\n`curl | bash` patterns.`-r`, `-f`, and `--hard`, including combined flags such as `-rf`.\nOne design decision is especially important: **GhostShell never executes the command it analyzes.**\n\nIt is an educational and preventive tool, not a shell, terminal agent, or automatic command runner.\n\nI designed GhostShell with a clear separation of responsibilities: deterministic rules classify risk, while the language model makes the explanation easier to understand.\n\n| Responsibility | Component | Why it matters | \n|---|---|---|\n| Risk classification | Rule engine | Provides deterministic, testable findings | \n| Command explanation | Local AI model | Converts technical syntax into beginner-friendly language | \n| Flag interpretation | Built-in glossary | Explains common options and combined flags | \n| Consequences and safer steps | AI informed by rule findings | Makes warnings more useful and actionable | \n| Fallback and response validation | Application logic | Avoids relying entirely on model-generated output | \n\nThe rule engine in `safety.py` analyzes commands against patterns associated with risky operations.\n\nThe classification levels are **High, Medium, Low, and Unknown**.\n\nThere is deliberately no *Safe* category. A command that does not match a known dangerous pattern has not thereby been proven harmless.\n\nThe AI integration in `ghost_ai.py` uses an Ollama-served model to generate natural-language explanations.\n\nRather than asking the model to determine risk entirely on its own, GhostShell supplies the rule findings and relevant flag glossary information as context.\n\nThe model can then explain:\n\nThe model is also instructed to treat the submitted command as untrusted data, reducing the risk of command text being interpreted as instructions to the AI.\n\nApplication-level validation rejects outputs that claim a command is entirely safe or risk-free. If the model is unavailable or produces an unacceptable response, GhostShell can use rule-based explanations instead.\n\nThis separation helps prevent the language model from simply talking its way out of a rule-based warning. It does not eliminate every possible classification or explanation error, so users should still inspect unfamiliar commands.\n\nGhostShell uses a small, modular Python architecture.\n\n`app.py`` safety.py``ghost_ai.py`` prompts.py``tests/`\nThe application combines deterministic Python logic with local language-model inference. This allows the rule engine to remain testable while the AI focuses on making its findings understandable.\n\n| Technology | Purpose | \n|---|---|\n| Python | Core application and rule engine | \n| Streamlit | Interactive user interface | \n| Ollama | Local model serving | \n| Qwen2.5 1.5B | Default open-weight language model | \n| pytest | Automated testing | \n\nInstall Python and [Ollama](https://ollama.com/download).\n\n```\ngit clone https://github.com/nehabohrapi/ghostshell-ai.git\ncd ghostshell-ai/ghostshell\n```\n\nOn Linux or macOS:\n\n```\npython -m venv .venv\nsource .venv/bin/activate\n```\n\nOn Windows:\n\n```\npython -m venv .venv\n.venv\\Scripts\\activate\npip install -r requirements.txt\nollama pull qwen2.5:1.5b\n```\n\nMake sure the Ollama service is running.\n\n```\nstreamlit run app.py\n```\n\nOpen [http://localhost:8501](http://localhost:8501) in your browser.\n\nTry entering `rm -rf *` to see how GhostShell analyzes a command associated with destructive file deletion. Do not execute it as an experiment.\n\n| Variable | Default | Purpose | \n|---|---|---|\n| `OLLAMA_HOST` | `http://localhost:11434` | Ollama server address | \n| `GHOSTSHELL_MODEL` | `qwen2.5:1.5b` | Model used for explanations | \n\nOther Ollama-supported models may work, depending on their availability and compatibility. Larger models, such as Qwen2.5 3B or Llama 3.2 3B, may provide different explanation quality but require additional system resources.\n\nGhostShell includes a pytest suite covering important behaviors, including:\n\nRun the tests with:\n\n`bash```\n\npytest\n\nThe goal is to test not only expected command classifications but also edge cases and failure paths.\n\nI wanted GhostShell to be more than an interface wrapped around a closed AI API.\n\nUsing an open-weight model through Ollama makes local inference possible. Developers can experiment with supported models, inspect the surrounding application logic, and adapt the tool without making a hosted proprietary model API a requirement for its default workflow.\n\nOpen-source technologies also make the safety logic easier to inspect and improve. Contributors can add patterns, test edge cases, review fallback behavior, and propose better explanations.\n\nThis is particularly important for a command-analysis tool. Users should be able to understand how warnings are generated instead of blindly trusting a model's confidence.\n\nThe combination of a deterministic rule engine and a local language model reflects the kind of innovation I want to explore: systems where AI adds usability, but important decisions are supported by explicit logic and testable behavior.\n\nOpen innovation makes that experimentation accessible to more developers—and gives the community a way to challenge, improve, and extend the design.\n\nThe terminal can be intimidating when you're learning.\n\nYou find a command that promises to fix an error or install a tool. It looks short. Someone online says it works. You copy it, paste it, and hope for the best.\n\nBut what if you had a friendly guide who explained the command before you took that step?\n\nThat is the spirit behind GhostShell.\n\nThe ghost isn't there to stop developers from learning or to frighten them away from powerful tools. It's there to encourage a pause—a moment to understand what a command does, what its flags mean, and what consequences it might have.\n\nI also wanted the experience to feel welcoming. A playful ghost, atmospheric visuals, and approachable explanations turn command inspection into something less intimidating for beginners.\n\nThe project follows one simple principle:\n\n**Understand first. Execute only when you're confident.**\n\nAnd GhostShell itself never executes anything for you.\n\nGhostShell is an educational command analyzer, not a formal security guarantee.\n\n`man` pages or `--help`, when uncertain.\nThe tool is designed to support judgment, not replace it.\n\nGhostShell is designed to be approachable for first-time contributors.\n\nOne of the easiest ways to contribute is to add a well-tested detection rule.\n\n`_r(...)` pattern in `tests/test_safety.py`.` pytest`.\nOther useful contributions include:\n\n`DROP`.\nThe goal is to make GhostShell more useful without pretending that a finite set of rules can identify every dangerous command.\n\nWith the default local setup, commands are sent to the Ollama server configured for GhostShell, normally running on the same machine.\n\nThis avoids sending command text to a hosted language-model API as part of the default explanation workflow. If you configure Ollama to use a remote server, the privacy implications change.\n\nStreamlit may collect anonymous usage statistics unless disabled in its configuration.\n\n**Challenge:** Hacktoberfest Open-Source AI Challenge — Week 4: Ghost in the Machine\n\n**Project:** [GhostShell on GitHub](https://github.com/nehabohrapi/ghostshell-ai)\n\n**Prize categories:** aourdino Q board\n\nGhostShell is my attempt to make terminal commands a little less mysterious.\n\nBy combining rule-based risk detection, local AI explanations, flag documentation, response validation, and a friendly interface, I wanted to build something that helps developers learn while encouraging more careful decisions.\n\nIt is not a replacement for understanding the terminal. It is a tool to help build that understanding.\n\nBecause sometimes, the best AI assistant isn't the one that executes a command for you.\n\nIt's the one that explains what could happen before you press Enter.\n\n**Meet GhostShell. Summon the explanation, not the execution.** 👻\n\nHappy Hacktoberfest!", "url": "https://wpnews.pro/news/ghostshell-ai", "canonical_source": "https://dev.to/nehabohrapi13/ghostshell-ai-24ll", "published_at": "2026-10-31 13:41:14+00:00", "updated_at": "2026-10-31 13:49:44.807020+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "large-language-models"], "entities": ["GhostShell", "Neha Bohra", "Ollama", "Streamlit", "Python", "GitHub", "Hacktoberfest"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/ghostshell-ai", "markdown": "https://wpnews.pro/news/ghostshell-ai.md", "text": "https://wpnews.pro/news/ghostshell-ai.txt", "jsonld": "https://wpnews.pro/news/ghostshell-ai.jsonld"}}