syxanash/maxheadbox

Tiny truly local voice-activated LLM Agent that runs on a Raspberry Pi

What it solves

Max Headbox provides a way to create a fully local, voice-activated AI assistant on a Raspberry Pi. It removes the need for cloud-based AI providers, ensuring privacy and offline capability while allowing the assistant to interact with physical hardware and automate tasks on the device.

How it works

The system uses a combination of local tools for voice processing and LLM inference:

  • Voice Activation: Uses Vosk for wake-word detection and faster-whisper for transcribing speech to text.
  • Intelligence: Runs LLMs (such as Gemma) locally via Ollama.
  • Agentic Logic: The frontend manages the agent's logic and can trigger "tools" (JavaScript modules) to execute specific actions. Some tools interact with the Raspberry Pi hardware via an Express.js and Python backend.
  • Safety: Supports a "dangerous" flag for specific tools, requiring the user to verbally confirm execution with "YES" or "NO".

Who it’s for

Hardware enthusiasts and Raspberry Pi users who want a private, on-device AI desk toy or home automation agent that can be expanded with custom tools.

Highlights

  • 100% Local: Operates entirely on-device without cloud dependencies.
  • Custom Tooling: Easy to add new capabilities by creating JavaScript modules in the src/tools/ directory.
  • Hardware Integration: Designed to work with Raspberry Pi 5 and compatible screens/coolers.
  • Safety Confirmation: Built-in confirmation flow for high-risk actions.
  • Visual Feedback: Includes an animated character UI to indicate the agent's state.