Home

COMSTAR AI

An always-on, embodied AI presence for your home.
It sees you, knows you, listens for you, and answers with a face.

Status: pre-alpha · License: Apache-2.0 · Platform: Raspberry Pi 4 · Brain: agentic-orchestration

---

What you get

A small screen on a Raspberry Pi, a camera, a microphone, and a speaker. It runs continuously. When you walk into frame it recognises you, greets you by name, and waits. You ask it something. An emblem avatar answers you out loud.

Behind that is a CrewAI-based, model-agnostic orchestration engine with dynamic planning, per-task MCP tools, session memory, and a learning loop. COMSTAR is a face for that engine, not a wrapper around a chatbot.

Everything runs on your own hardware. No cloud dependency required for Phase 1.

---

Wiki map

Section	Start here
Understand	What is COMSTAR · Architecture · Attention Model
Build	Getting Started · Installation · Configuration
Interfaces	Contracts — every cross-process boundary
Operate	Runbook · Dev Loop · Troubleshooting
Decide	ADR Index
Plan	Roadmap · Milestones · Progress Tracker
Art	IMAGE-PROMPTS — Gemini prompts for every wiki image

---

Design principles

Principle	Meaning
Local by default	Nothing leaves the LAN unless you explicitly wire it to.
Thin client, fat brain	The Pi does I/O. Speech compute prefers AO-advertised sidecars on the AI server.
Identity is the session	Face recognition selects the AO session and its memory.
The room is a tool	Presence and vision are MCP tools the planner can call.
Latency is a feature	If a response takes longer than ~15s, the interaction is broken.

---

Architecture at a glance

Raspberry Pi 4 (terminal)          AI server (RTX 4000 Ada)
├ camera / mic / display           ├ agentic-orchestration :8765
├ comstar-audio (wake + VAD)       ├ speech STT/TTS :8090 / :8091
├ comstar-bridge (Dart)            └ CodeProject.AI :32168
└ Chromium kiosk (SVG avatar)

Full diagram: Architecture.

---

Phase 1 success criterion

Walk up → greeted by name → ask a question → spoken answer under 15 seconds.

See Roadmap and Progress Tracker for where we are.

---

Quick links for operators

• Enroll a face → Vision & Face Enrollment
• Start processes → Runbook
• Mac + Pi loop → Dev Loop
• Something broken → Troubleshooting
• Inject events without walking into frame → Dev Loop § Dev console

---

_{Not a mystical AI. A tool you engineered — transparent, hackable, fast.}