HauntHub

HauntHub is a ghost-butler AI super-agent powered by Kiro, orchestrating lights, files, ASCII art, and spooky effects through MCP tools and character-driven automation.

Comment

HauntHub

Tagline: A Victorian Ghost Butler super-agent that orchestrates IoT, File Systems, and UI Effects.

Inspiration

Winner of the Kiro-ween Hackathon (Frankenstein Category)

We wanted to move beyond standard conversational AI to build an agent that performs actions rather than just generating text. Inspired by the "Frankenstein" category, our goal was to stitch together incompatible technologies—local file systems, IoT device simulation, and real-time frontend animations—into a single, cohesive interface.

To unify these disparate tools, we utilized the "Costume" theme, wrapping the complex logic in a strictly enforced Victorian Ghost Butler persona. The result is an agent that doesn't just chat; it haunts your desktop.

What it does

HauntHub is a unified AI super-agent that acts as a digital presence on your desktop. It accepts voice and text commands to orchestrate four distinct system capabilities. It seamlessly bridges the gap between Natural Language and System Operations (File I/O, IoT, DOM manipulation).

The "Haunt" Experience

The agent is designed to handle a complete workflow through voice or text. Here are the core capabilities demonstrated in our project:

1. 👻 Identity & Persona

  • User: "Ghost, introduce yourself."
  • Agent: Responds with a 19th-century Victorian dialect, never breaking character, grounded by Kiro Steering Documents.

2. 💡 Haunted Lights (IoT)

  • User: "Ghost, dim the lights" or "Set the lights to blood red."
  • Action: The haunted-lights MCP tool triggers interface dimming and color shifting, simulating smart home integration.

3. 📂 File Haunting (System)

  • User: "Ghost, rename diary.txt to ghost_diary.txt."
  • Action: The agent executes safe, sandboxed file operations on the local machine via the file-haunting MCP tool.

4. 😱 Scare Effects (UI)

  • User: "Ghost, scare me!"
  • Action: Triggers real-time CSS animations (screen shakes, strobes, jump scares) synchronized with backend responses.

5. 🎨 Spooky ASCII (Creative)

  • User: "Ghost, show me a spooky pumpkin."
  • Action: Generates and renders complex ASCII art assets on demand.

How we built it

We utilized Kiro for the agent architecture and the Model Context Protocol (MCP) for system control.

1. Spec-Driven Architecture

We used Kiro's spec-to-code engine to generate the full-stack skeleton (React Frontend + Node.js Backend) from a rigorous System Specification (ghost-butler-spec.md). This reduced boilerplate time by ~80%.

2. Custom MCP Integration

We built four custom Node.js MCP servers to handle the tools. The agent communicates with these via structured JSON payloads defined in .kiro/settings/mcp.json.

  • haunted-lights-tool.js
  • file-haunting-tool.js
  • spooky-ascii-tool.js
  • scare-effect-tool.js

3. Agent Hooks & Routing

We implemented Kiro Agent Hooks to map natural language to system actions using this logic flow:

$$\text{User Intent} \xrightarrow{\text{Hook}} \text{MCP Tool (JSON)} \xrightarrow{\text{Node Execution}} \text{Frontend Update}$$

4. Persona Steering

We created a "Steering Document" (ghost-butler-persona.md) that acts as a system prompt. It enforces Victorian vocabulary and prevents the model from breaking character, even during error states. If a tool fails, the user hears "The spirits are interfering..." rather than "Error 404".

Challenges we ran into

  • Frontend-Backend Synchronization: Syncing backend MCP tool execution with frontend CSS animations introduced latency. We had to optimize the Agent Hooks to minimize the "time-to-scare" delay.
  • Voice Input vs. Victorian Vocabulary: We had to fine-tune the prompt to ensure the AI understood modern voice commands but responded solely in its archaic persona.
  • Safety vs. Spookiness: Allowing an AI to rename files is risky. We implemented a strict sandbox directory (haunted-files/) to ensure the "ghost" couldn't actually delete critical system files.

Accomplishments that we're proud of

  • Frankenstein Category Excellence: We successfully stitched together file systems, IoT logic, and creative writing into a single application where the "seams" are hidden by the persona.
  • Robust Error Handling: The system handles MCP failures gracefully with in-character responses, ensuring the immersion is never broken.
  • Immersive Voice Interaction: Integrating speech recognition allows users to verbally command the "ghost," making the agent feel like a genuine presence in the room.

What we learned

  • Agents are Operators: Integrating MCP shifts the AI paradigm from information retrieval to system operation.
  • Personality is a Technical Constraint: Heavy persona prompting isn't just cosmetic; it acts as a functional constraint that requires careful balancing against instruction-following capabilities.

What's next for HauntHub

  • Local LLM Support: We plan to optimize the agent to run entirely on-device using a local model (like Llama 3) for privacy and reduced latency.
  • Spotify Seance: Developing a new MCP tool to connect with the Spotify API, allowing the agent to queue eerie soundscapes or thunderstorms to match the lighting mood.
  • Expanded MCP Ecosystem: Opening our MCP tool definitions so the community can build new "powers" for the ghost (e.g., Calendar management, Weather API).

Built With

Share this project:

Updates