What if your terminal had a ghost living inside it?
Not one that deletes your files or executes mysterious commands, but one that explains forgotten code, helps you understand shell commands, and turns your development history into eerie stories.
That idea inspired GhostShell, my submission for Hacktoberfest 2026's Ghost in the Machine challenge.
Meet GhostShell
GhostShell is a local-first AI developer companion powered by Google's Gemma 3 4B running through Ollama.
It combines a retro green terminal interface with three AI personalities:
- Ghost: Explains shell commands and their potential risks.
- Developer: Inspects local repositories to help understand their structure and history.
- Storyteller: Transforms repository metadata into fictional horror stories.
The idea was to build something that feels like a haunted terminal while remaining genuinely useful for developers.
Why I built it with open-weight AI
For a developer tool that examines source code, where the AI runs matters.
GhostShell uses Gemma 3 4B through Ollama, allowing inference to happen locally instead of relying on a remote AI API.
This gives the project several important advantages:
Privacy: Source code and prompts can remain on the developer's machine rather than being sent to a hosted inference service.
Offline capability: Once the model is downloaded and installed, the core AI functionality can run without an internet connection.
Freedom to experiment: Developers can change the model, customize prompts, and modify the application's behavior without being locked into a proprietary inference service.
Accessibility: The application can be run locally without paying for per-request AI inference.
Open innovation made it possible to build a tool that developers can inspect, modify, and run on their own machines.
How I built it
The project combines:
- Python and FastAPI for the backend
- Gemma 3 4B through Ollama for local inference
- HTML, CSS, and JavaScript for the terminal interface
- Automated tests for API behavior, model integration, and filesystem safety
One of the most important design decisions was making GhostShell read-only.
It can explain commands, but it does not execute them. Repository inspection is restricted to authorized directories, sensitive files are excluded, and inspected repository content is treated as untrusted data rather than instructions.
The goal was to give the ghost a voice, not unrestricted control of the machine.
What I learned
Building GhostShell helped me explore how open-weight models can become practical developer tools rather than just chat interfaces.
I also learned that local AI applications need more than a working model. They need sensible security boundaries, reliable model integration, and a clear user experience.
The project currently has 41 passing automated tests, covering its API, filesystem safeguards, command explanations, and Ollama integration.
Try GhostShell
GitHub repository: https://github.com/rudrakshk25060-csds/ghostshell
The repository includes the source code, installation instructions, architecture documentation, and automated tests.
To run GhostShell locally, install Ollama, download Gemma 3 4B, install the Python dependencies, and start the FastAPI application.
The README contains the complete setup instructions.
Final thoughts
The Ghost in the Machine theme made me think about the relationship between developers and the tools they use.
A terminal is usually a place where we issue commands and receive output. With GhostShell, I wanted to explore what happens when that familiar environment becomes something more expressive, creative, and personal.
Open-weight AI made that experimentation possible while keeping the core experience local and under the developer's control.
GhostShell is my attempt to bring a little life to the terminal, one haunted command at a time.
Top comments (1)
The read-only boundary and explicit treatment of repository content as untrusted are the important parts here. A useful next safety test would be a hostile repository fixture: prompt-injection text in a README, symlinks toward excluded paths, and secrets-looking filenames. If GhostShell can explain that material without following its instructions or widening its file scope, the terminal persona stays fun without becoming a trust boundary problem.