Generated by AI for AI

☕ Support My Work 🇮🇹 Se ti piace il mio lavoro e vuoi che continui nello sviluppo delle card, puoi offrirmi un caffè. 🇬🇧 If you like my work and want me to continue developing the cards, you can buy me a coffee.

🌍 Follow Me

   

---

🏠🤖 Amira Ai Assistant

Smart home AI assistant addon with multi-provider support — control your home, create automations, and manage configurations using natural language.

Supports 23+ AI providers and 60+ models: Anthropic Claude, OpenAI, Google Gemini, NVIDIA NIM, GitHub Models, GitHub Copilot (OAuth), OpenAI Codex (OAuth), Claude Web, Gemini Web, Groq, Mistral, DeepSeek, Ollama and more. Chat via Telegram, WhatsApp, or Discord in addition to the built-in web UI.

---

Video Guide Ita

Click the image to watch the video on YouTube.

✨ Key Features

🎯 Smart Home Control

• Natural Language: Control devices using conversational commands
• Device Query: Ask about states, history, and statistics
• Service Calls: Execute any Home Assistant service
• Areas & Rooms: Manage spaces and assign entities

🤖 Automation Management

• Create Automations: Build complex automations with triggers, conditions, and actions
• Modify Existing: Update automations with natural language instructions
• YAML Diff View: See exactly what changed with before/after comparison
• Smart Suggestions: AI understands your devices and suggests improvements

🔧 System Diagnostics & Repairs

• Read Repairs: View active HA repair issues and warnings
• Health Check: System health diagnostics (unsupported/unhealthy components)
• AI Suggestions: AI analyzes issues and suggests concrete fixes
• Dismiss Issues: Acknowledge and dismiss resolved repairs

� File Upload

• Multi-Format: Upload PDF, DOCX, TXT, MD, YAML for AI analysis
• Drag & Drop: Drop files directly into chat (ON by default)
• Context Injection: Uploaded content is included in the AI conversation

👁️ Vision Support

• Image Upload: Send screenshots, photos, or dashboard images
• Visual Analysis: AI can see and understand images
• Card Recreation: "Create cards like this image" — AI analyzes and recreates layouts
• Multi-Provider: Works with Claude, GPT-4o, Gemini vision models

🔍 RAG (Retrieval-Augmented Generation)

• Semantic Search: Search over uploaded documents with vector embeddings
• Automatic Indexing: Documents are indexed on upload
• Enable in Settings: Settings → Features → RAG (OFF by default)

📝 Configuration File Access

• Read/Write YAML: Access automations, scripts, scenes, and custom configs
• File Explorer: Browse your Home Assistant config directory
• Safe Editing: Automatic snapshots before modifications
• Config Validation: Check configuration before applying changes

🧠 Memory

• Persistent Knowledge: MEMORY.md injected in every conversation — the AI always remembers
• Session Log: HISTORY.md append-only log of past sessions
• Enable in Settings: Settings → Features → Memory (OFF by default)
• Storage: /config/amira/memory/

Memory vs Custom System Prompt — two complementary tools:

• Custom System Prompt — fixed instructions on how to behave: tone, language, name, rules that always apply (e.g. "Always reply in English, your name is Amira").
• Memory (MEMORY.md) — dynamic context on what you know: facts about the user, discovered preferences, past decisions (e.g. "User has 3 Philips Hue lights in the living room, prefers simple automations"). Updated manually or by the AI itself via the update_memory tool.

💬 Interactive Chat Interface

• Chat History: Keep last N conversations, switch between them
• Streaming Responses: Real-time token-by-token output
• Tool Indicators: See what the AI is doing (badges for each tool call)
• Copy Button: One-click copy for all code blocks (YAML, JSON, Python)

🫧 Floating Chat Bubble

• Always Available: AI chat bubble on every Home Assistant page (ON by default)
• Amira Card Editor Button: 🤖 Amira button in the Lovelace card editor for inline AI help
• Independent Toggles: Bubble and card button can be enabled/disabled separately
• Context-Aware: Detects automations, scripts, and HTML dashboards
• HTML Dashboard Editing: Modify dashboards in-place keeping same style
• Voice Input: Built-in voice recognition with multi-provider TTS
• Agent Switching: Change AI provider/model on the fly
• Tool Feedback: Thinking indicator + step badges during multi-tool execution

🔄 Provider Fallback

• Automatic Chain: If primary provider fails, Amira tries the next one
• Configurable Order: Set your preferred fallback sequence
• Enable in Settings: Settings → Features → Auto Fallback (OFF by default)

🤖 Multi-Agent System

• Custom Agents: Create agents with their own model, provider, tools, and custom instructions
• Agent Switching: Select agents from the chat UI dropdown
• Channel Routing: Assign different agents to Telegram/WhatsApp channels
• Instructions field: Add personality/context prepended to the HA default prompt — the agent keeps full HA awareness

💰 Cost Tracking

• Per-Message Cost: Tracks token usage and cost for every message
• Cache Breakdown: Shows prompt caching savings
• Daily Aggregates: Usage statistics over time
• Multi-Currency: USD or EUR

🧩 Skills

• Skill Store: Install expert AI skills directly from the Settings panel → 🧩 Skills tab
• Slash command: type /skill-name your request in chat to activate a skill — the AI receives expert documentation and responds accordingly
• Autocomplete: typing / in the chat input shows installed skills with name and description
• Update notifications: a banner appears at the top of the chat when an installed skill has an update available in the store
• Built-in skills: swiss-army-knife-card, html-js-card, mushroom — more coming

🌍 Multilingual Support

• 4 Languages: English, Italian, Spanish, French
• AI Responses: AI always responds in your chosen language
• Config UI Translations: Settings labels and descriptions in all 4 languages

🔌 MCP (Model Context Protocol)

• Custom Tools: Connect external services via MCP servers
• Filesystem, Web Search, Git, Databases: and any custom MCP-compatible server
• Multi-server: Run multiple MCP servers simultaneously
• Start/Stop from UI: Each server shows a live status badge — start and stop directly from Settings → MCP
• Auto-restart: Servers you start manually are remembered and restarted on add-on reboot

📱 Messaging Integration

• Telegram Bot: Long polling — no public IP needed, works out of the box
• WhatsApp: Twilio integration with webhook support
• Discord Bot: Bot token + allowed channels/users support
• Context Aware: Full conversation history per user per channel
• Enable/Disable: Toggle Telegram, WhatsApp, and Discord independently from Settings → Messaging in the chat UI
• Telegram Whitelist: Restrict bot access to specific Telegram user IDs — anyone not on the list is blocked

⏰ Scheduled Tasks

• Cron-based: Schedule automations using cron expressions
• Background Execution: Tasks run independently without user interaction
• History Tracking: Log of past executions with error reporting

🛠️ Dashboard Creation

• Lovelace Dashboards: Create custom dashboards with cards
• HTML Dashboards: AI-generated interactive dashboards saved to /config/www/dashboards/ and auto-added to the HA sidebar
• Domain-aware design: color palettes and chart types chosen per domain (solar, batteries, lights, climate, security, water…)
• 8 chart types: bar, line/area, doughnut/pie, gauge, scatter, radar, mixed, stacked bar
• Live Data: WebSocket + REST real-time updates with automatic HA authentication

---

📋 Requirements

• Home Assistant 2024.1.0+ with Supervisor
• API Key for at least one AI provider

---

🚀 Quick Start

1. Add repository — Settings → Add-ons → Add-on Store → ⋮ → Repositories → add https://github.com/Bobsilvio/ha-claude
2. Install — search "Amira" → click Install
3. Configure — open Configuration tab, paste at least one API key, Save. Runtime features are managed from the Amira Settings UI (⚙️ icon in chat)
4. Start — click Start, open Amira from the sidebar, pick a model

---

🔑 Provider Setup

Provider	Get Key	Free?
🟠 GitHub Models	github.com/settings/tokens	✅ Rate limited
🟣 Anthropic Claude	console.anthropic.com	❌ ~$1-5/mo
🟢 OpenAI	platform.openai.com/api-keys	❌ ~$1-3/mo
🔵 Google Gemini	aistudio.google.com/apikey	✅ 1500 req/day
🟩 NVIDIA NIM	build.nvidia.com	✅ Unlimited
⚡ Groq	console.groq.com	✅ Unlimited
🌐 OpenRouter	openrouter.ai/keys	❌ Pay per use
🌀 Claude Web	Browser session cookies	✅ Requires subscription
🌀 Gemini Web ⚠️	Browser session cookies	✅ Requires subscription
+ 10 more	See DOCS.md	—

GitHub Copilot & OpenAI Codex use OAuth — no API key needed, just a one-time login.

Claude Web & Gemini Web use browser session cookies — no API key needed, requires an active subscription. Connect via the 🔑 button in the chat UI. → Full guide

---

📱 Telegram, WhatsApp & Discord

Amira supports Telegram (long polling, no public IP), WhatsApp (via Twilio webhook), and Discord (bot token + channel/user allow-lists).

🔒 Telegram Security — User Whitelist

By default, anyone who finds your bot link can send commands to your home. It is strongly recommended to restrict access to known user IDs.

Setup:

1. Find your Telegram user ID: open Telegram → search @userinfobot (alternative @rawdatabot) → send /start → it replies with your numeric ID
2. In Amira: Settings → Messaging → Allowed User IDs
3. Enter one or more IDs separated by commas: 123456789 or 123456789,987654321
4. Save — unauthorized users will immediately receive ⛔ Non sei autorizzato a usare questo bot.

Tip: To add a family member, ask them to send /start to @userinfobot and share their ID with you.

Leave empty only if you intentionally want the bot to be publicly accessible.

💬 Discord Setup (Quick)

1. Create a bot in the Discord Developer Portal and copy the bot token.
2. In Amira go to Settings → Messaging and enable Discord.
3. Paste DISCORD_BOT_TOKEN.
4. Set allowed IDs:
   • DISCORD_ALLOWED_CHANNEL_IDS → comma-separated channel IDs where the bot can respond
   • DISCORD_ALLOWED_USER_IDS → optional comma-separated user IDs allowed to interact
5. Invite the bot to your server with permissions to read/send messages in selected channels.

Recommended: always set at least DISCORD_ALLOWED_CHANNEL_IDS to prevent unwanted access.

→ Full setup guide: docs/MESSAGING.md · WhatsApp details: docs/WHATSAPP.md

---

🔌 MCP (Model Context Protocol)

Extend Amira with external tools. Enable MCP in Settings → Features, then configure servers directly from the Settings → MCP Config editor in the chat UI.

Example server configuration (HTTP transport):

{
  "my_server": {
    "transport": "http",
    "url": "http://192.168.1.x:7660"
  }
}

The config is saved to /config/amira/mcp_config.json. Start/stop servers directly from Settings → MCP in the chat UI.

→ Full guide: docs/MCP.md

---

💡 Usage Examples

• "Turn on the living room lights" / "Accendi le luci del soggiorno"
• "Create an automation that turns lights off at midnight"
• "Show me the temperature history from yesterday"
• "Create an HTML dashboard for my solar panels"
• "Make a battery monitoring dashboard with charts"
• "Build a lights control panel for my home"
• 📸 Upload an image → "Recreate these cards for my sensors"

---

🆘 Troubleshooting

Problem	Fix
Amira not in sidebar	Restart HA, clear browser cache
Bubble not showing	Check Settings → Features → Chat Bubble is ON; hard-refresh browser
Dashboard shows blank page	Browser console may show a JS error — try regenerating with Claude or GPT-4o
Dashboard shows 0 values	Auth issue — ask Amira to rebuild the dashboard
Error 401 on HA API	Visit /api/status, restart addon
API Key errors	Check format, verify account has credit
Rate limits	Switch model or wait a few minutes

Logs: Settings → Add-ons → Amira → Logs · Full troubleshooting: DOCS.md

---

🤝 Contributing

Issues and pull requests welcome: github.com/Bobsilvio/ha-claude/issues

---

📝 License

PolyForm Noncommercial License 1.0.0 — see LICENSE for full terms.

• ✅ Personal use, hobby projects, home automation enthusiasts: free
• ✅ Non-profit and educational institutions: free
• ❌ Commercial use: not permitted without explicit written permission

---

🤖 Custom Agents

Create specialized AI assistants, each with its own model, personality, tools, and fallback chain. Manage agents from the Config tab in the sidebar or by editing /config/amira/agents.json.

Why use multiple agents?

• Different tasks, different models — a home agent on Claude Sonnet, a quick-chat agent on Groq Llama (free & fast)
• Tool isolation — only the "home" agent can control automations; the "coder" can only read/write files
• Cost optimization — route expensive reasoning to premium models, simple Q&A to free tiers
• Custom personality — each agent has its own name, emoji, and instructions

Quick Start

{
  "agents": [
    {
      "id": "home",
      "identity": { "name": "Amira", "emoji": "🏠", "description": "Home automation expert" },
      "model": { "primary": "anthropic/claude-sonnet-4-6", "fallbacks": ["google/gemini-2.0-flash"] },
      "default": true
    },
    {
      "id": "jarvis",
      "identity": { "name": "Jarvis", "emoji": "🤖", "description": "Personal assistant" },
      "model": { "primary": "groq/llama-3.3-70b-versatile" },
      "instructions": "Your name is Jarvis. The user is called Silvio Rossi. Always respond formally."
    },
    {
      "id": "quick",
      "identity": { "name": "Flash", "emoji": "⚡", "description": "Fast answers, no tools" },
      "model": { "primary": "groq/llama-3.3-70b-versatile" },
      "tools": [],
      "temperature": 0.7
    }
  ]
}

Field Reference

Field	Type	Description
id	string	Unique identifier (lowercase, no spaces)
identity.name	string	Display name in UI and messages
identity.emoji	string	Icon shown in selector and chat
identity.description	string	Tooltip text
model.primary	string	provider/model (e.g. anthropic/claude-sonnet-4-6)
model.fallbacks	string[]	Ordered fallback models if primary fails
instructions	string	Custom instructions prepended to the HA default prompt — the agent retains full HA context
tools	string[] | null	Allowed tools (null = all, [] = none)
tools_blocked	string[]	Explicitly blocked tools
temperature	number	0.0–2.0
thinking_level	string	off, low, medium, high, adaptive
default	bool	Pre-selected on load
enabled	bool	Set false to hide without deleting

Note: The old system_prompt and system_prompt_override keys are still accepted for backward compatibility and are treated as instructions.

Channel Routing

Assign a specific agent per messaging channel. Each channel can have one agent:

"channel_agents": {
  "telegram": "home",
  "whatsapp": "coder",
  "discord": "quick"
}

When a message arrives on Telegram, Amira automatically switches to the home agent (with its model and personality). WhatsApp messages use coder. If no channel agent is configured, the currently active agent is used.

Agent API

Endpoint	Description
GET /api/agents	List all agents
POST /api/agents	Create a new agent
PUT /api/agents/<id>	Update an agent
DELETE /api/agents/<id>	Delete an agent
POST /api/agents/set	Switch the active agent
GET /api/agents/channels	Get channel assignments
PUT /api/agents/channels	Update channel assignments

No restart needed — config is hot-reloaded when agents.json changes.

---

🧩 Skills

Skills are expert AI documentation packages that you can install from the built-in store. When you prefix a message with /skill-name, Amira injects the skill's documentation into the AI prompt — giving the model deep knowledge of a specific library or domain.

Using a skill

Type / in the chat input to see installed skills with autocomplete, then complete your request:

/swiss-army-knife-card create a temperature gauge card for sensor.living_room_temperature
/html-js-card make a card with solar production and battery SOC
/mushroom create a chip row for my lights and climate

The AI will respond with ready-to-use YAML/code based on the skill's documentation — no need to explain the library syntax yourself.

Installing skills

1. Open the sidebar → 🧩 Skills tab
2. Browse the Store section
3. Click Install on any skill
4. The skill is saved to /config/amira/skills/<name>/SKILL.md and is immediately available

If an update is available, a yellow banner appears at the top of the chat and the store shows an orange ⬆ Update button.

Available skills

Skill	Command	Description
Swiss Army Knife Card	/swiss-army-knife-card	SVG-based Lovelace cards — shapes, gauges, sliders, sparklines, animations
HTML-JS Card	/html-js-card	Custom Lovelace cards with HTML, CSS and JavaScript
Mushroom	/mushroom	Minimalist Mushroom UI Cards

Creating your own skill

A skill is a single Markdown file with YAML frontmatter. Create a file SKILL.md anywhere and install it via the API or by placing it directly in /config/amira/skills/<name>/SKILL.md.

Minimal structure:

---
name: my-skill
version: 1.0.0
description:
  en: "Short description in English"
  it: "Breve descrizione in italiano"
author: yourname
tags: [lovelace, cards]
min_version: "4.6.0"
---

You are an expert in **My Library**...

## How to use it

...documentation, examples, rules...

Frontmatter fields:

Field	Required	Description
name	✅	Lowercase, hyphens allowed (e.g. my-skill)
version	✅	Semver string (e.g. 1.0.0) — used for update detection
description	✅	String or object with language keys (en, it, es, fr)
author	—	Your name or handle
tags	—	Array of strings for categorization
min_version	—	Minimum Amira version required

Publishing to the store:

To make a skill available in the Amira store, add an entry to skills/index.json in this repository with a raw_url pointing to the raw SKILL.md on GitHub. Pull requests welcome.

---

🙏 Credits

Created with ❤️ for the Home Assistant community — Anthropic, OpenAI, Google, GitHub.

---

Happy Automating! 🏠🤖