GhostShell AI

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.

Hacktoberfest Open-Source AI Challenge — Week 4: Ghost in the Machine Have 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? I 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. That inspired GhostShell : a friendly, ghost-themed AI assistant that explains terminal commands before you run them . Instead of executing commands, GhostShell analyzes them, identifies potential risks, explains their flags in beginner-friendly language, and suggests safer next steps. Think of it as a little ghost sitting beside your terminal, whispering: “Wait a second. Do you know what this command is about to do?” 👻 GitHub repository: https://github.com/nehabohrapi/ghostshell-ai https://github.com/nehabohrapi/ghostshell-ai GhostShell 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. Try it locally by following the setup instructions below. GhostShell is a local-first, AI-assisted terminal command analyzer built with Python and Streamlit. Its purpose is to help developers understand potentially dangerous commands before running them, especially when they are learning Linux, Git, shell scripting, or developer tooling. curl | bash patterns. -r , -f , and --hard , including combined flags such as -rf . One design decision is especially important: GhostShell never executes the command it analyzes. It is an educational and preventive tool, not a shell, terminal agent, or automatic command runner. I designed GhostShell with a clear separation of responsibilities: deterministic rules classify risk, while the language model makes the explanation easier to understand. | Responsibility | Component | Why it matters | |---|---|---| | Risk classification | Rule engine | Provides deterministic, testable findings | | Command explanation | Local AI model | Converts technical syntax into beginner-friendly language | | Flag interpretation | Built-in glossary | Explains common options and combined flags | | Consequences and safer steps | AI informed by rule findings | Makes warnings more useful and actionable | | Fallback and response validation | Application logic | Avoids relying entirely on model-generated output | The rule engine in safety.py analyzes commands against patterns associated with risky operations. The classification levels are High, Medium, Low, and Unknown . There is deliberately no Safe category. A command that does not match a known dangerous pattern has not thereby been proven harmless. The AI integration in ghost ai.py uses an Ollama-served model to generate natural-language explanations. Rather than asking the model to determine risk entirely on its own, GhostShell supplies the rule findings and relevant flag glossary information as context. The model can then explain: The 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. Application-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. This 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. GhostShell uses a small, modular Python architecture. app.py safety.py ghost ai.py prompts.py tests/ The 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. | Technology | Purpose | |---|---| | Python | Core application and rule engine | | Streamlit | Interactive user interface | | Ollama | Local model serving | | Qwen2.5 1.5B | Default open-weight language model | | pytest | Automated testing | Install Python and Ollama https://ollama.com/download . git clone https://github.com/nehabohrapi/ghostshell-ai.git cd ghostshell-ai/ghostshell On Linux or macOS: python -m venv .venv source .venv/bin/activate On Windows: python -m venv .venv .venv\Scripts\activate pip install -r requirements.txt ollama pull qwen2.5:1.5b Make sure the Ollama service is running. streamlit run app.py Open http://localhost:8501 http://localhost:8501 in your browser. Try entering rm -rf to see how GhostShell analyzes a command associated with destructive file deletion. Do not execute it as an experiment. | Variable | Default | Purpose | |---|---|---| | OLLAMA HOST | http://localhost:11434 | Ollama server address | | GHOSTSHELL MODEL | qwen2.5:1.5b | Model used for explanations | Other 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. GhostShell includes a pytest suite covering important behaviors, including: Run the tests with: bash pytest The goal is to test not only expected command classifications but also edge cases and failure paths. I wanted GhostShell to be more than an interface wrapped around a closed AI API. Using 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. Open-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. This 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. The 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. Open innovation makes that experimentation accessible to more developers—and gives the community a way to challenge, improve, and extend the design. The terminal can be intimidating when you're learning. You 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. But what if you had a friendly guide who explained the command before you took that step? That is the spirit behind GhostShell. The 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. I also wanted the experience to feel welcoming. A playful ghost, atmospheric visuals, and approachable explanations turn command inspection into something less intimidating for beginners. The project follows one simple principle: Understand first. Execute only when you're confident. And GhostShell itself never executes anything for you. GhostShell is an educational command analyzer, not a formal security guarantee. man pages or --help , when uncertain. The tool is designed to support judgment, not replace it. GhostShell is designed to be approachable for first-time contributors. One of the easiest ways to contribute is to add a well-tested detection rule. r ... pattern in tests/test safety.py . pytest . Other useful contributions include: DROP . The goal is to make GhostShell more useful without pretending that a finite set of rules can identify every dangerous command. With the default local setup, commands are sent to the Ollama server configured for GhostShell, normally running on the same machine. This 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. Streamlit may collect anonymous usage statistics unless disabled in its configuration. Challenge: Hacktoberfest Open-Source AI Challenge — Week 4: Ghost in the Machine Project: GhostShell on GitHub https://github.com/nehabohrapi/ghostshell-ai Prize categories: aourdino Q board GhostShell is my attempt to make terminal commands a little less mysterious. By 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. It is not a replacement for understanding the terminal. It is a tool to help build that understanding. Because sometimes, the best AI assistant isn't the one that executes a command for you. It's the one that explains what could happen before you press Enter. Meet GhostShell. Summon the explanation, not the execution. 👻 Happy Hacktoberfest