GhostShell: a haunted terminal that "possesses" your shell (Hacktoberfest Week 4)

GhostShell is a Python command-line interface (CLI) that connects to a model running on the user's machine through Ollama. This AI-powered tool provides contextual commentary on terminal commands, explains unfamiliar commands, and flags dangerous ones with standard code rules. The AI never executes anything—only the user's confirmed commands are executed.

GhostShell was initially a last-minute Halloween project, but it proved to be surprisingly useful. It not only provides commentary but also teaches new users, while seasoned users receive a personality where the shell had none. The AI models behind GhostShell are local and open-weight, making it an example of open innovation.

The project consists of four small modules: main.py, prompts.py, ai.py, and terminal.py. main.py handles the main loop and routes normal commentary versus explaining a command. prompts.py holds the AI's persona and hard rules, ensuring it never invents command output or claims success. ai.py sends a single HTTP request to the model, while terminal.py manages display, risk checks, confirmation, and execution.

Safety is a critical aspect of GhostShell, as the AI never runs commands—it only echoes the user's typed text. A 404 response prompts the model to pull the model again, while a connection refusal results in the ghost remaining silent. The system avoids silent degradation into fake analysis by checking for command injection vulnerabilities and using deterministic risk checks with 18 regex patterns.

Two-stage confirmation is implemented, asking the user, "Execute this exact command? [y/N]" (defaulting to no). Flagged commands receive additional warnings, and the user must type "EXECUTE" to proceed. The AI's whisper provides context without authority, and the user retains ownership of the boundaries.

To test GhostShell, users only need to pull an open-weight model (such as Qwen2.5:3b), create a virtual environment, install the required packages, and run the main.py script. The AI provides feedback on commands like "git status," offers lessons on using "git log --oneline," and warns about risky commands like "Remove-Item -Recurse .\some-test-folder." The ghost is always watching, whether for good or ill.