⚠️ Beta software — Kyber is production-ready for home use but still evolving rapidly. Your AI now has a key to the house. Literally.Kyber lets an AI control your lights, thermostats, automations, scripts, and dashboards — in natural language, no confirmation required (in Autopilot Mode). It won't judge you for having 47 automations that do the same thing, but it might just clean them up if you ask. The AI can modify your Home Assistant configuration — automations, scripts, entities and dashboards. Always review proposals before executing them, keep backups, and remember we are not responsible for your living room turning into a disco at 3am.
Kyber is a local AI chat panel for Home Assistant, powered by your Ollama instance. Chat with your smart home, manage entities, edit automations, and build dashboards — all without leaving HA.
- In HACS → Integrations → ⋮ → Custom repositories
- Add
https://github.com/pgroene/kyberas an Integration - Find Kyber in the HACS store and install
- Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration → search for Kyber
Or use the quick-add button:
- 💬 AI Chat — ask questions and give commands in natural language; automatic language detection with locale-specific vocabulary hints (Dutch, German, French, Spanish, Italian, Portuguese)
- 📋 Proposal Cards — review changes before they're applied, with one-click Undo
- ⚡ Autopilot Mode — auto-execute proposals for hands-free operation
- ✏️ Automation & Script Editor — CodeMirror 6 YAML editor with AI assistance
- 📊 Dashboard Editor — edit Lovelace dashboards as YAML, create new dashboards
- 🔧 Slash Commands —
/dashboard,/automation,/script,/blueprint,/area,/memory,/updateand more — see docs/slash-commands.md - 🏷️ Kyber Labels — tag entities with
kyber:*labels (e.g.kyber:important,kyber:appliance) via/area label; Kyber uses these to prioritise context - 🤖 AI Entity Narrator — on startup, Kyber batches all entities and generates rich descriptions and natural-language search aliases (e.g. "koffiezetapparaat" →
switch.onoff_keuken_espresso). Alias quality is filtered for plausibility. See docs/narrator.md - 📍 Proactive Area Suggestions — when you mention a room and nearby entities have no area assigned, Kyber shows a one-click assignment card. See docs/area-suggestions.md
- 🔒 100% Local — all AI inference runs on your own Ollama instance; nothing leaves your network
- ☁️ Cloud AI support — optionally route through Azure AI Foundry, OpenAI (or compatible: Groq, Mistral, OpenRouter), or Anthropic (Claude) instead of a local model
- 🔌 MCP Server — expose Kyber as an MCP tool so ChatGPT, Claude Desktop, Cursor and other AI clients can control your home. See docs/mcp.md
- 🔌 Integration Explorer — on startup Kyber automatically indexes every loaded HA integration: sensor names, entity IDs, and natural-language capability descriptions as searchable knowledge facts
- 🔬 Deep Analyzer — on-demand AI extraction of durable home facts across 8 analytical lenses: daily routines, device inventory, occupancy patterns, time/location triggers, energy usage, safety rules, entity relationships & dependencies, and automation purpose & use case
- 🧠 Hybrid memory retrieval — in-memory TF-IDF embedding with cosine similarity + keyword overlap blending; selected facts streamed to the live progress card
- 🔁 Tool-calling loop — up to 5 rounds of tool calls per turn; duplicate call detection with targeted redirect hints; tool name alias resolution
- 🗂️ Conversation sessions — named sessions with full rolling history and automatic compaction
- 🔄 Self-update —
/update forceinstalls the latest GitHub release directly, bypassing HACS. See docs/slash-commands.md - 🐞 Kyber Debug panel — a dedicated sidebar entry (
/kyber-debug) with five tabs: Memory, Last Turn, Status, Logs, Tests. See docs/debug-panel.md - 📦 Debug bundle download — every turn produces a downloadable ZIP with the full system prompt, tool log, memory picks, and response
See docs/installation.md for full setup instructions.
Requirements: Home Assistant 2025.2+, Ollama with a model pulled, HA Ollama integration configured.
# Docker dev setup
docker compose -f docker-compose.dev.yml up
# then open http://localhost:8123
After install, Kyber registers two sidebar panels:
| Panel | URL | Purpose |
|---|---|---|
| Kyber | /kyber |
Main chat interface |
| Kyber Debug | /kyber-debug |
Memory browser, last turn details, entity narrator progress, live logs |
Kyber requires an Ollama model configured through the HA Ollama integration. Not all models perform equally — smaller models often fail to produce the structured plan blocks Kyber needs for action requests.
Based on the May 2026 eval report (5 runs × 3 real-home scenarios):
| Model | Score | Notes |
|---|---|---|
mistral-nemo:latest |
🥇 14/15 (93%) | Recommended — reliable plan output, handles Dutch, 1-round answers from memory |
qwen2.5:latest |
✅ check | Not yet in the formal eval; community reports suggest strong structured output — worth trying if mistral-nemo is too slow on your hardware |
qwen3:4b-instruct |
🥈 10/15 (67%) | Good for read-only queries; fails action plans in Dutch |
llama3.2:latest |
🥉 4/15 (27%) | Unpredictable token usage; often skips plan blocks entirely |
Recommendation: use mistral-nemo:latest. It reliably emits structured plan blocks, bridges Dutch entity name gaps via tool calls, and answers location queries in a single round. 3B–4B class models work for questions but are not reliable for executing actions.
See docs/eval-report-2026-05.md for full methodology, timing data, and failure analysis.
The background entity narrator uses a separate model call that only needs to produce short structured aliases — not full plan blocks. A smaller, faster model is ideal here.
Based on the May 2026 narrator bench (19 models, batch sizes 1 and 10, warmup-corrected):
| Model | Quality@10 | Batch 10 time | Notes |
|---|---|---|---|
llama3.2:3b |
✅ 100% | 3.7s | 🏆 Recommended — 12× faster than mistral-nemo, 1.9 GB |
phi3:mini |
✅ 95% | 9.1s | Strong backup — slightly larger at 2.3 GB |
llama3:latest |
✅ 100% | 11.0s | Reliable but slower |
mistral-nemo:latest |
✅ 100% | 44.0s | Former recommendation — still works, just slow for narration |
qwen3:*, deepseek-r1:7b |
❌ 0% | — | Reasoning/thinking models — format not compatible |
Recommendation: use llama3.2:3b for narration. See docs/narrator-bench-report-2026-05.md for the full breakdown.
| Doc | Contents |
|---|---|
| docs/installation.md | Prerequisites, manual install, Docker dev setup, version bumping, tests |
| docs/settings.md | All settings — config flow, options sections, Debug Status tab; ASCII screen sketches |
| docs/chat-and-ai.md | Chat basics, proposal cards, autopilot, conversation history, entity autocomplete |
| docs/slash-commands.md | All slash commands: /dashboard, /automation, /script, /blueprint, /area |
| docs/editor.md | Automation/script editor, dashboard editor, Lovelace card type reference |
| docs/pipeline.md | End-to-end request pipeline — context build, hybrid memory retrieval (TF-IDF embeddings), tool loop, response cleanup, per-turn snapshot, debug bundle, debug-mode flag |
| docs/architecture.md | Frontend, backend endpoints, context building, plan/action system |
| docs/eval-report-2026-05.md | 📊 May 2026 eval report — building the real-home prompt eval harness, what we fixed, and model comparison (mistral-nemo vs llama3.2 vs qwen3) |
| docs/narrator-bench-report-2026-05.md | 📊 May 2026 narrator bench — 19 small models tested for entity narration quality and speed; llama3.2:3b wins (12× faster than mistral-nemo, same quality) |
| Layer | Technology |
|---|---|
| AI provider | HA Ollama integration via ai_task.async_generate_data() (HA 2025.2+) |
| Backend | Modular Python custom component — 14+ modules covering context building, tool execution, knowledge store, session management, debug diagnostics, integration explorer, and deep analysis |
| Frontend | Shadow DOM web component with CodeMirror 6 YAML editor |
| Module | Responsibility |
|---|---|
http_api.py |
Main AI request handler — prompt assembly, tool-call loop, intent classification, mode rules |
action_execution.py |
Plan action executor — service calls, area/label assignments, undo tracking |
knowledge.py |
TF-IDF knowledge store — add, search, rate, purge facts |
knowledge_integration.py |
Knowledge HTTP views — CRUD, shallow & deep analyze, feedback, purge |
integration_explorer.py |
Startup integration indexer — sensors, entity IDs, capability facts for all platforms |
deep_analyzer.py |
AI-powered automation/script/blueprint fact extractor (8 analytical lenses) |
session_and_storage.py |
Chat session management — multi-session store, history, summarization |
debug_and_diagnostics.py |
Per-turn debug snapshots, bundle ZIP builder, bug report, debug-mode flag |
intent_and_context.py |
Intent classification, quick-intents, home-state context builder |
tool_execution.py |
Tool handler dispatch, alias resolution, domain priority ranking |
language_hints.py |
Language detection and locale-specific vocabulary hints (Dutch + extensible) |
domain_docs.py |
Per-domain documentation injected into tool context |
response_processing.py |
Response cleanup — strip tool echoes, narration, rewrap action blocks |
source.py |
Raw YAML readers for automations, scripts, blueprints + content-hash memos |
| Endpoint | Purpose |
|---|---|
POST /api/kyber/complete |
Prompt + history + HA context → AI response + plan |
POST /api/kyber/execute |
Execute plan actions (service calls, area/label/entity management) |
POST /api/kyber/parse_yaml |
YAML string → JSON config (used before saving via HA API) |
POST /api/kyber/summarize |
Compact conversation history into a summary |
GET /api/kyber/progress |
Live progress events (polled by the frontend during AI turns) |
GET /api/kyber/history |
Retrieve chat history for the active session |
GET /api/kyber/sessions |
List all named sessions |
POST /api/kyber/sessions/name |
Rename a session |
GET /api/kyber/knowledge |
List knowledge store entries |
POST /api/kyber/knowledge |
Add or update a knowledge entry |
POST /api/kyber/knowledge/analyze |
Shallow automation analysis → knowledge facts |
POST /api/kyber/knowledge/analyze_deep |
Deep AI-driven analysis across all 8 lenses |
POST /api/kyber/knowledge/feedback |
Rate knowledge entries (👍/👎) |
POST /api/kyber/knowledge/purge |
Delete knowledge entries by filter |
GET /api/kyber/debug/last_turn |
Last-turn debug snapshot (system prompt, tool log, knowledge used) |
GET /api/kyber/debug/tool_history |
Ring buffer of recent tool calls |
GET /api/kyber/debug/status |
Integration status + entity/area counts |
GET /api/kyber/debug/bundle |
Download per-turn debug ZIP by request_id |
GET /api/kyber/debug/bug-report |
Download sanitised bug report ZIP |
GET/POST /api/kyber/debug/mode |
Read or toggle debug-mode flag |
MIT — see LICENSE