This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine
GhostShell is a terminal companion for the bug you already met. The tagline is “Your terminal remembers what you forget.”
You paste a traceback, say what you were doing, and point it at one project directory. It writes a structured reading: a title, a category, ranked guesses, the lines those guesses rest on, what it has not seen, a risk level, and a check you can run afterward. If a similar incident is already in the local ledger, the screen names that incident’s id. It does not announce that the old fix will work again.
The ghost is the voice. The evidence is the constraint. Suggested commands are shown first. Nothing runs until you approve it, and a local policy check can still refuse.
I read the theme as memory with a boundary. A haunted machine that whispers fixes and then types them would be a costume on a chatbot. The interesting ghost is the one that remembers the earlier failure and still hands you the keyboard.
GhostShell is a local terminal app. There is no hosted website. This silent video is the interface itself, captured from the app with the synthetic phantom project and the rule-based reader, so it does not wait on a model. It runs about one minute: the ledger, the lantern reading with the traceback quoted back, the two earlier incident ids, the pip show command held for approval, the pattern, and the ledger rows.
The file in the repository is docs/demo/ghostshell-demo.mp4. The player above works after that file is pushed to main.
python -m venv .venv
.venv\Scripts\activate
python -m pip install -e ".[dev]"
$env:GHOSTSHELL_HOME = "$PWD\demo-home"
python -m ghostshell.app --seed-demo
--seed-demo inserts five fake incidents for examples/phantom_app. That folder imports a module named lantern on purpose, fails an assertion in ritual.py, and contains one file that is not valid Python. There are no credentials in it.
The walkthrough with expected text is docs/DEMO_SCRIPT.md. For the fix review, assess python -m pip show lantern and approve that read-only check. Leave python -m pip install lantern unapproved. The demo is not supposed to install a package.
On this machine, Ollama 0.6.6 already had gemma3:4b. Pointing Settings at that tag and submitting the same lantern traceback returned JSON that validated: a title, a category, hypotheses, and command argument lists. The source line said local AI and named the model. The pictures above are the rule-based path, because the screenshot pilot turns Ollama off. I have not disconnected the network and then relaunched, so I am not calling the offline path verified.
Your terminal remembers what you forget.
Every bug leaves a trace. GhostShell is a local-first terminal companion for investigating errors, recalling earlier incidents, and reviewing a fix before anything runs. The personality is a ghost. The reasoning is the evidence you pasted, the files you selected, and the incidents already stored on this machine.
This build is for the Hacktoberfest 2026 Open-Source AI Challenge, Week 4: “Ghost in the Machine.” Inference stays on a loopback Ollama server. There is no cloud model client and no telemetry.
Error output disappears into a scrollback buffer. The next time the same import fails, or the same test breaks, the earlier context is gone. Sending that traceback to a hosted model also sends whatever the log happened to contain.
GhostShell keeps a SQLite ledger on disk, compares a new error with those rows, and refuses to run a suggested command until…
Repository: https://github.com/Abishethvarman/GhostShell
License: MIT. Python 3.11+, Textual, Rich, Pydantic, SQLite, and pytest. Model weights are not in the repository.
flowchart TD
user[Developer] --> ui[Textual UI]
ui --> redact[Redaction and size limits]
redact --> memory[Ledger search]
memory --> manager[Model manager]
manager --> ollama[Loopback Ollama]
manager --> rules[Rule-based reader]
ollama --> parser[Pydantic parser]
parser --> ui
rules --> ui
ui --> policy[Command policy]
policy --> runner[Argument-list process]
ui --> ledger[(SQLite ledger)]
The only HTTP client talks to 127.0.0.1, localhost, or ::1. A cold Gemma load once answered HTTP 500. The client retries that once, then tries plain JSON mode if a schema is rejected. If the reply still is not valid JSON, the rule-based reader answers and says so.
if exc.code == 500 and isinstance(body.get("format"), dict):
try:
return self._request("POST", "/api/chat", body=body, timeout=timeout)
except urllib.error.HTTPError as second:
exc = second
if exc.code in {400, 500} and isinstance(body.get("format"), dict):
relaxed = dict(body)
relaxed["format"] = "json"
Memory ids are replaced after the model replies. Whatever id the model wrote is discarded. The ids on screen are the ones the ledger search returned.
analysis.memory_incident_ids = [item.incident_id for item in matches]
note += " A previous fix is not assumed to resolve this incident."
Commands run as an argument list with shell=False, a timeout, and a capped capture. A suggestion that arrives as one shell string is displayed and cannot be run.
The open-source AI is local inference through Ollama. The preferred family is Gemma. Settings can select gemma2:2b (the configured default, a small tag), gemma3:4b, gemma2:9b, or qwen2.5:3b. GhostShell does not run ollama pull. If the selected tag is missing, the dashboard lists what is installed and the séance uses the deterministic reader.
The project is built around that call, with the ledger in front of it:
A closed debugging API wants the traceback. Tracebacks contain paths, hostnames, tokens, and the occasional password someone echoed. Sending that away so a chat window can say “try reinstalling” is a bad trade, and the answer disappears when the tab closes.
An open-weight model behind Ollama changes the shape of the tool:
gemma3:4b.
Open weights are what make the memory acceptable. The ghost can keep the earlier bug because the ledger never leaves the machine, and it still has to ask before it touches the project.
I have not published an agent-session transcript for this build, so there is no agent-session embed yet. The decisions are in the repository: loopback only, no automatic model download, memory ids taken from SQLite rather than from the model, and no command without an approval and a second policy check.
The moment that landed was not a jump scare. It was the second lantern failure.
The synthetic app imports lantern and fails. The ledger already had that traceback, marked with what someone claimed they did last time. GhostShell did not say the old install would save this one. It quoted the new error, printed the old incident ids, and stopped at python -m pip show lantern until that read-only check was approved.
That is the haunting I wanted. The machine remembers the trace. It does not get to finish the ritual.
Gemma is the model the app is set up to call, and gemma3:4b through local Ollama produced a validated investigation on this machine.