GhostShell: A Local AI Coding Assistant with a Haunted Terminal Twist

Hacktoberfest Open-Source AI Challenge: Ghost in the Machine Submission 👻🌼

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

I built GhostShell, a local AI coding assistant designed to help developers understand code, debug errors, and work with terminal commands more safely.

The idea behind GhostShell is simple: what if your terminal had a ghost that could help you understand your code?

GhostShell combines a haunted terminal-inspired interface with local AI inference. Instead of building another generic chatbot, I wanted to create a coding assistant that feels like a developer tool, with a little personality of its own.

Command Oracle: Helps explain terminal commands and their behavior.

Error Exorcist: Helps investigate errors and understand possible fixes.

Safer Fix: Focuses on safer approaches when dealing with potentially destructive commands or changes.

It also includes model selection, backend and Ollama status indicators, response streaming, copy actions, and the ability to stop generation.

One important part of the project is its deterministic safety handling. During testing, I found that a small local model could confidently invent a Git option, claiming that git rm --preview was valid. GhostShell's safety layer was designed to handle the known command case with a verified explanation instead of trusting the model to get it right.

That experience reminded me that a coding assistant needs more than a good prompt. It also needs checks around the model's output.

GhostShell currently runs locally with its React frontend, FastAPI backend, and Ollama inference.

A publicly hosted, fully functional demo is not available yet. The frontend and backend require additional deployment configuration for the local AI inference workflow.

GitHub repository: https://github.com/Kshitij342/ghostshell

The repository includes the frontend, backend, safety guardrails, and automated tests.

The project is organized around a React/Vite frontend and a Python FastAPI backend, with Ollama handling local model inference.

I built GhostShell using the following stack:

Tailwind-style utility classes/CSS and Lucide icons for the interface and visual details.

Ollama for running an open-weight language model locally.

Qwen2.5 3B for local coding-assistant responses.

The backend provides endpoints for health checks, Ollama status and model discovery, normal chat, and streaming chat.

One of the most important development challenges was handling incorrect model output. A model can generate a convincing explanation that is still technically wrong. I added deterministic safety handling for the specific Git command case and regression tests to help prevent the same failure from returning.

The final backend test run passed 39 tests, and the frontend production build completed successfully with Vite. I also manually checked the normal and streaming API responses for the known Git command case.

This is still an evolving project, but the testing process helped me think more carefully about the boundary between AI-generated suggestions and application-level safety rules.

Open innovation made this project possible because I could experiment with an open-weight model locally instead of relying entirely on a closed, hosted AI API.

Running inference through Ollama gave me more control over model selection and made it possible to build and test the application on my own machine. I could observe the model's mistakes, improve the surrounding safety logic, and repeat the tests without building the entire project around a paid inference API.

It also made the limitations more visible. Local models can be useful, but they are not automatically reliable. Open tooling gives developers the freedom to experiment, inspect behavior, and build additional safeguards where needed.

For me, that is one of the strongest reasons to build with open-source AI: we can learn from both what works and what fails.

I used AI-assisted development tools while building and debugging GhostShell, including help with implementation, regression testing, and the local model integration.

I have not included a DevRelay session link because I do not have a verified public session URL to share.

The idea of a ghost in the machine is usually about something hidden inside technology that behaves in unexpected ways.

While building GhostShell, I experienced a very practical version of that idea: a local AI model could confidently explain a command that did not exist.

It looked convincing until I checked the actual command behavior.

That became an important lesson for the project. The goal isn't to make AI sound confident. It's to make the tool useful while recognizing when its output needs to be constrained or verified.

Sometimes, the ghost isn't in the terminal. It's in the answer.

I have not listed partner prize categories because I have not verified which categories GhostShell qualifies for. I will select the applicable categories from the official challenge rules before submitting.

Built as part of the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine.

Thanks for reading, and feedback is welcome!