This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine
GhostShell: Your Terminal Has a Soul—and It’s Here to Protect You
What I Built
GhostShell is a local-first AI terminal companion with a ghostly personality and a practical job: help developers understand what happened when a command fails, and make risky commands harder to run by accident.
I interpreted “Ghost in the Machine” as a presence in the place developers spend so much time: the terminal. But this ghost isn’t just there to narrate errors. GhostGuard checks commands before they reach the runner. It classifies risk deterministically, asks for a fresh approval before supported caution-level commands, and blocks dangerous commands by default. AI can explain an error, but it cannot approve or execute a command.
The local CLI supports a deliberately limited set of workflows rather than pretending to replace PowerShell, Bash, or CMD. It also keeps redacted session history in local SQLite. The React demo shows three clearly labeled simulations—a dangerous deletion command, a port conflict, and a missing dependency. Those scenarios are browser-only; the public demo has no connection to a real shell.
Demo
GhostShell
Your terminal has a soul. And this time, it's here to protect you.
GhostShell is a local-first AI developer safety companion. It reviews a deliberately small set of terminal commands, blocks dangerous operations, requires a fresh human approval for caution-level work, and can investigate command errors with Gemma running locally through Ollama.
GhostShell is a working MVP, not a PowerShell, CMD, or Bash replacement. The public website is a separate, static product demo: its scenarios are simulated in the browser and cannot execute commands.
Why GhostShell?
Developer assistants often need command output to help diagnose a failure. Sending that evidence to a hosted model can expose private project details. GhostShell keeps the actual runner, history, and optional AI analysis on the developer's machine. Deterministic GhostGuard rules remain active when Ollama is unavailable, and a model can explain an error but cannot authorize or run a command.
Features
- Interactive Rich…
Code
GhostShell
Your terminal has a soul. And this time, it's here to protect you.
GhostShell is a local-first AI developer safety companion. It reviews a deliberately small set of terminal commands, blocks dangerous operations, requires a fresh human approval for caution-level work, and can investigate command errors with Gemma running locally through Ollama.
GhostShell is a working MVP, not a PowerShell, CMD, or Bash replacement. The public website is a separate, static product demo: its scenarios are simulated in the browser and cannot execute commands.
Why GhostShell?
Developer assistants often need command output to help diagnose a failure. Sending that evidence to a hosted model can expose private project details. GhostShell keeps the actual runner, history, and optional AI analysis on the developer's machine. Deterministic GhostGuard rules remain active when Ollama is unavailable, and a model can explain an error but cannot authorize or run a command.
Features
- Interactive Rich…
How I Built It
GhostShell is built in Python, with a FastAPI informational API, SQLite storage, and a React/Vite frontend. The local AI integration uses Gemma 3 1B through Ollama. The model is intended to analyze bounded, redacted command output and offer troubleshooting explanations. If Ollama or the model is unavailable, GhostGuard and the CLI can still work without AI.
The important design decision was to keep AI out of the security decision loop. Deterministic rules classify commands, approvals are tied to the exact command and working directory, and the runner only accepts a small allowlist. Processes use argument lists and shell=False, with timeouts and bounded output. The public demo uses fixed scenarios and does not execute commands.
I implemented and tested the Ollama integration, but couldn’t verify live Gemma inference in this environment because Ollama wasn’t installed. The project reports that clearly rather than pretending the model is ready. The Python suite passes 28 tests, and the frontend production build succeeds.
Why Does Open Innovation Matter?
Open-weight models and local runtimes make it possible to put AI closer to sensitive developer workflows without requiring command output to go to a hosted AI provider. After the model is downloaded, local inference can also work without an internet connection, depending on the machine and runtime.
Just as importantly, an open project makes the boundaries inspectable: developers can see what the runner supports, how risk is classified, what gets sent to the model, and where the limitations are. GhostShell is designed to work without a paid AI API—and without silently falling back to one.
The Spirit of It
I wanted the ghost to feel less like another chatbot and more like a careful presence at your shoulder: the one that says, “Wait—are you sure?” before an irreversible command, and stays to help investigate when something breaks.
The spooky part is the storytelling. The protective part is the engineering.
Prize Categories
No partner-specific prize category claimed. GhostShell uses Gemma through Ollama and does not claim use of partner technologies.
Top comments (0)