Poltergeist: A Ghost That Whispers at Your PowerShell Prompt
What I Built
Poltergeist is a read-only ghost for PowerShell. It remembers a redacted version of recent command history and offers short whispers at later prompts: sometimes eerie, sometimes funny, sometimes unexpectedly kind.
I interpreted “Ghost in the Machine” as a presence in the place developers already spend time: the terminal. The ghost never executes, edits, blocks, or replaces a command. It observes, redacts, and speaks only when its local rules allow it.
The project includes four selectable personas: Victorian Ghost, Ofrenda, COBOL Spirit, and Gremlin. Each has its own style, examples, and a pool of offline whispers.
Demo
There isn’t a hosted demo or video yet. You can run Poltergeist locally on Windows with Python 3.11+ and PowerShell:
python -m pip install -e .
ghost init
Setup previews the PowerShell profile change, backs up an existing profile, lets you choose a persona, and checks for a local Ollama server. Restart PowerShell after setup, run a few commands, and the ghost can leave a whisper at a later prompt. Try ghost mood or ghost remember as well.
Ollama is optional. Without it, Poltergeist uses its built-in offline whispers.
Code
GitHub repository: akshrakothari/Poltergeist
The repository includes the Python package, PowerShell integration, persona files, tests, latency measurement and model evaluation scripts, and a build log.
How I Built It
Poltergeist is written in Python and uses Typer for its command-line interface, Rich for terminal output, and SQLite for local command history. Persona definitions are stored in TOML files.
For AI inference, Poltergeist connects to Ollama on the local machine. The default model is llama3.2:3b; qwen2.5:3b is another suggested option. The Ollama client accepts only loopback URLs and disables proxy environment settings.
The PowerShell hook captures command text, exit status, elapsed time, working directory, and timestamp. It redacts command text before persistence, and the event store applies redaction again as a second safeguard. Before requesting a whisper, Poltergeist builds a compact brief and can include up to three facts derived from SQL queries over local history. A validator checks the response’s length and format and rejects unsupported numbers, quotes, and emoji. If the model is unavailable or the answer fails validation, Poltergeist falls back to a deterministic handwritten whisper.
The ghost speaks at the next prompt. Model work runs in a detached process; if it takes too long, the whisper is skipped instead of making the shell wait. The project also includes ghost hush, quiet hours, ghost remember, and ghost exorcise to remove its marked PowerShell hook and local data.
Why Does Open Innovation Matter?
A terminal history can contain sensitive details about someone’s work. Running inference locally means Poltergeist doesn’t need to send command context to a hosted AI service. Users can choose which supported local model to run, inspect how the app prepares the prompt, and keep history on their own machine.
Open models also let the project remain useful when inference is unavailable: the built-in persona lines work offline. The model is an optional local collaborator, rather than a remote service the shell depends on.
My Agent Session
I don’t have a saved agent-session link to include.
The Spirit of It
The ghost waits until a later prompt, so a comment arrives like an echo of the command that just finished. It might offer a gentle line after an error or a quiet acknowledgment after a familiar command.
The Ofrenda persona is written as a warm, respectful ancestor-like presence. It avoids imitating a cultural ritual or inventing cultural claims. I wanted the project’s DĂa de los Muertos interpretation to leave room for remembrance while treating the theme with care.
Prize Categories
None. Poltergeist does not currently use a partner’s technology for a prize category.
Top comments (0)