PhantomShell: A Haunted Terminal Powered by Local AI

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

What I Built

PhantomShell is a haunted terminal companion that gives ordinary command-line sessions a little supernatural personality.

Instead of sending terminal activity to a hosted AI service, PhantomShell is designed around a local open-weight model. It reacts to commands and their output with short, context-aware messages: sometimes eerie, sometimes funny, and occasionally genuinely useful.

Run a command, get its result, and hear what the Phantom has to say.

For example:

$ git status

PHANTOM:
Ah... a repository in the shadows.
You have uncommitted changes. The ghosts are watching.

The spooky personality is the presentation. The useful part is the local context: PhantomShell can use the current session's command and output to explain errors, point out failed tests, or suggest what to inspect next.

Implementation note before publishing: Keep only the features that are implemented and tested in the final version. Do not describe planned capabilities as completed ones.

Demo

The project is intended to run locally. A hosted demo is not required for the core experience because the model inference happens on the user's machine.

Code

Github repository

Suggested repository contents:

• phantomshell/ — terminal application and session handling
• phantomshell/ai/ — Ollama client and prompt construction
• tests/ — command parsing, safety and model-response tests
• README.md — installation, setup and usage instructions

How I Built It

The core idea is to keep the AI layer replaceable and local.

Proposed stack

• Python for the terminal application and process management.
• Ollama to run an open-weight language model locally.
• Qwen3 8B as the initial model to experiment with, subject to the machine's available memory and the model's current license.
• Rich for readable terminal output, colors and panels.
• SQLite or in-memory session state for optional local conversation context.

The command flow is intentionally simple:

1. The user enters a command inside PhantomShell.
2. PhantomShell runs it through the user's configured system shell and captures its exit code and output.
3. The app builds a small context package containing the command, output and recent session turns.
4. Ollama generates a short response locally.
5. PhantomShell prints the response alongside the real command output.

The model is not the shell and does not get unrestricted authority over the machine. Commands are entered and executed by the user; AI suggestions are advisory. Any future feature that can execute a suggested command should require explicit confirmation.

Why Does Open Innovation Matter?

A terminal session can reveal a surprising amount: project names, directory structures, error messages, internal hostnames and sometimes secrets accidentally printed by tools. Sending that context to a third-party API is not a requirement for a playful developer companion.

Running an open-weight model locally gives PhantomShell a different set of trade-offs:

• Local-first privacy: command context can stay on the developer's machine instead of being sent to a hosted model.
• Offline potential: once the model is downloaded, the core response loop can work without an internet connection.
• Model choice: the inference layer can be swapped as better or smaller open-weight models become available.
• Control: prompts, response length, personality and context handling can be inspected and changed.
• Predictable experimentation costs: local inference does not require a per-request API bill, although it still uses hardware, electricity and storage.

The point is not that a local model is automatically better at every task. A hosted model may be more capable for some difficult questions. The interesting part is that a terminal companion does not need a cloud connection just to react to a command. Open models make that private, modifiable experience possible.

The Spirit of It

The command line has always felt a little mysterious. A command disappears into the prompt, work happens somewhere out of sight, and an answer comes back.

PhantomShell makes that feeling literal.

The Phantom is not meant to pretend to be a real spirit. It is a small character living beside the tools developers already use: a reminder that even familiar workflows can be made playful, personal and a little strange.

And unlike an actual ghost, this one can be switched off.

Prize Categories

Applying for best use of Gemma and overall project

Happy Halloween and happy hacktoberfest!!!