Haunted Terminal: Project Story
Inspiration
I got tired of Googling shell commands. Even as an experienced developer, I'd forget the exact syntax for things like "find files modified in the last week" or complex grep patterns. When Google released Gemini CLI, I was excited—until I realized every command I typed was being sent to their servers. My company's scripts, my file paths, everything going to the cloud.
I wanted the convenience of natural language without sacrificing privacy. So I built Haunted Terminal using local Ollama instead.
What I Learned
Prompt engineering is harder than it looks. Early versions hallucinated commands constantly. The breakthrough was adding domain-specific examples—when someone asks about files, show file examples. When they ask about processes, show process examples. This cut hallucinations from 30% to under 5%.
Privacy requires discipline. No telemetry, no analytics, no "just this one API call." Everything had to work offline with local SQLite databases. It's more work upfront but worth it.
Terminal UX matters. I added color coding, loading animations, and command previews. The "haunted" theme with ghost emojis makes it less intimidating. People actually enjoy using it.
Safety can't be an afterthought. After accidentally running rm -rf / during testing, I built a three-tier safety system. Destructive commands get red warnings and require explicit confirmation.
How I Built It
Built with Python, using Ollama for local AI inference and Rich for terminal formatting. The core loop is simple: take natural language, send it to Ollama with carefully crafted prompts and examples, validate the output, show a preview, then execute if confirmed.
Architecture
┌─────────────────────────────────────────────┐
│ User (Natural Language) │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ CLI Interface │
│ • Input validation │
│ • Command preview │
│ • Themed output │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Ollama Client │
│ • Prompt engineering │
│ • Domain detection │
│ • Example selection │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Local Ollama (llama3.2) │
│ • Command interpretation │
│ • 100% local processing │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Command Executor │
│ • Syntax validation │
│ • Safety classification │
│ • Execution & output capture │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ History & Learning │
│ • SQLite database │
│ • Success/rejection tracking │
│ • Pattern learning │
└─────────────────────────────────────────────┘
Key features:
- Intelligent retry: Type "retry" and it generates a completely different command, learning from what you rejected
- Rituals: Multi-step workflows you can save and replay
- Memory: Learns from every successful command
- Knowledge base: Add your own custom commands
Challenges
Challenge 1: Same command on retry. Ollama kept generating identical commands. Solution: Track rejections and explicitly tell Ollama "NEVER generate these commands again."
Challenge 2: Invalid syntax. Commands like find . -mtime 7-14 (not valid). Solution: Added 50+ correct examples and explicit warnings about common mistakes.
Challenge 3: Slow inference. Ollama takes 3-5 seconds. Solution: Added smooth loading animations and Ctrl+C cancellation so it feels responsive.
Challenge 4: Testing AI. How do you test non-deterministic outputs? Solution: Property-based testing for logic, pattern matching for AI outputs, and a comprehensive manual test suite.
Results
Haunted Terminal is faster, more private, and more accurate than Gemini CLI. It's completely free, works offline, and includes features Gemini doesn't have. 182 tests passing, 95%+ accuracy on command generation.
Most importantly: your commands never leave your machine.
What's Next
Considering shell integration for inline suggestions, a plugin system for community domains, and optional collaborative learning where users can anonymously share successful patterns.
The goal remains the same: make the terminal accessible without compromising privacy.
\
Log in or sign up for Devpost to join the conversation.