Séance

Inspiration

As a huge fan of Supernatural, I've always been fascinated by the mystical and the paranormal. The show's iconic scenes where characters communicate with spirits inspired me to ask: What if we could recreate that eerie, spine-tingling experience using AI?

The Kiroween hackathon theme was the perfect catalyst. Halloween + AI + real-time collaboration = the ultimate spooky tech experience. I wanted to build something that wasn't just functional, but genuinely haunting an app that gives you chills when the planchette starts moving on its own.

What it does

Séance is a real-time multiplayer Ouija board experience where an AI "spirit" responds to your questions. Here's what makes it special:

🎭 Multi-user sessions — Gather friends (2-12 people) for a virtual séance
🔮 Animated planchette — Watch it glide letter-by-letter across the board, revealing the spirit's message
🌙 Haunting UI — Dark theme with candle-lit atmosphere and immersive sound effects
👻 Cryptic AI personality — The spirit speaks in riddles, avoiding direct answers like a true supernatural entity
⚡ Real-time sync — WebSocket-powered instant updates across all participants

How we built it

The tech stack was built for performance, atmosphere, and scale:

Backend:

FastAPI with async WebSockets for real-time communication
SQLAlchemy + PostgreSQL (Supabase) for session persistence
Google Gemini 2.0 Flash for AI-powered spirit responses
Comprehensive steering docs to shape the spirit's cryptic personality

Frontend:

Next.js 15 with React 18 for a modern, responsive UI
Framer Motion for butter-smooth planchette animations
Tailwind CSS for the dark, haunting aesthetic
Howler.js for ambient audio and sound effects
Zustand for state management

DevOps:

Docker containerization
Heroku (backend) + Vercel (frontend)
Supabase for managed PostgreSQL

The secret sauce: Kiro's steering docs. I created a 2000+ word spirit-personality.md that defines exactly how the AI should behave—cryptic, eerie, never giving straight answers, occasionally referencing the user's past questions. This makes every séance feel genuinely supernatural.

Challenges we ran into

WebSocket reliability — Ensuring real-time sync across multiple users without message loss required careful connection management and reconnection logic.
Planchette animation timing — The letter-by-letter reveal had to feel natural, not robotic. I spent hours tuning the spring physics and timing intervals.
AI personality consistency — Getting Gemini to stay "in character" as a mysterious spirit was tricky. The solution was comprehensive steering docs with explicit rules about what the spirit should never do.
TTS on cloud hosting — Edge TTS worked locally but failed on Heroku due to Microsoft's rate limiting. Had to disable it for the demo.
Supabase connection pooling — PgBouncer's transaction mode doesn't support prepared statements. Switching to session pooler fixed it.

Accomplishments that we're proud of

🎨 The UI is genuinely haunting — Not just "dark mode," but a full atmospheric experience with real Ouija board imagery
🤝 True multiplayer — Multiple people can join and see the planchette move simultaneously
🧠 The AI actually feels like a spirit — Thanks to steering docs, it never breaks character
📱 Works on any device — Responsive design from mobile to desktop
⚡ Fast and reliable — Sub-second response times with Gemini 2.0 Flash

What we learned

Steering docs are incredibly powerful — A well-written personality guide completely transforms AI behavior
Agent hooks save hours — Automated formatting, testing, and code quality checks
WebSockets need love — Real-time features require careful error handling and reconnection logic
Atmosphere matters — Sound effects and animations turn a "chat app" into an experience

What's next for Séance

🔊 Voice input — Speak your questions aloud (even creepier!)
📱 Mobile app — Native iOS/Android with haptic feedback when the spirit arrives
🎭 Multiple spirits — Different AI personalities with unique speaking styles
🌐 Public rooms — Join random séances with strangers worldwide
🏆 Séance history — Save and share your creepiest spirit encounters