⚠️ Important Notice (Breaking Changes):
This version now uses Home Assistant's AI Task (ai_task.generate_data) pipeline instead of calling OpenAI directly.
After updating from a version before 2.0.0, you MUST reconfigure the integration and select a compatible AI Task entity.

---

✨ Features

Natural voice commands: "Create a task…" or "Add a task…"* 🗣️

• Supports project, due date, priority, labels, recurrence and more 📅
• Optional: speech correction, auto voice label, default due date, user assignment
• Supports 11 languages 🌐 📖 Voice commands in all 11 languages

---

📦 Requirements

• Home Assistant with a voice assistant set up
• HACS
• Running Vikunja instance + API token with correct permissions
• Configured Home Assistant AI Task entity (from the ai_task.generate_data pipeline)

---

⚙️ Installation (HACS) | Video Guide

⏱️ Create your first task in under 2 minutes!

• In HACS → Search: Vikunja Voice Assistant → Install

• Restart Home Assistant

• Go to Settings → Devices & Services → Add Integration

• Search: Vikunja Voice Assistant

• Fill out setup form (Vikunja URL, API token, AI Task entity, options)

• Vikunja API Token → User Settings → API Tokens

• Set the following permissions:

• Labels: Create and Read All

• Projects: Read All, Projectusers (optional - for user assignment)

• Tasks: Create

📹 Video Guide

• AI Task entity Video Guide OpenRouter

Select the Home Assistant ai_task entity that is configured to run your preferred LLM via ai_task.generate_data.

Note: this integration relies on Home Assistant's AI Task pipeline (ai_task.generate_data). You can use any AI provider compatible with AI Task (examples: Ollama, OpenAI, Google Gemini, OpenRouter). See AI & LLM setup and the AI Task integration for details:

• AI & LLM setup: LINK

• AI Task (ai_task) integration: LINK

• ✅ Done – Just say "create a task" !

---

🔧 Configuration Options

Option	Purpose	Example/Default
Speech correction	Fix common speech-to-text errors	Enabled
Auto voice label	Attaches/creates a voice label	Enabled
Default due date	Used if no date & no project given	tomorrow
Default due date choices	none, tomorrow, end\of\week, end\of\month	tomorrow
Enable user assignment	Assign tasks to existing users	Disabled
Detailed response	Speak back project, labels, due date, assignee, priority & repeat info	On

---

🤖 AI Conversation Agent (Recommended)

Append this to your Home Assistant Voice Assistant’s conversation Agent custom instructions:

If the user mentions or implies creating or adding a new task,
always call this tool (do not leave any field empty):

tool_name: VikunjaAddTask
tool_args: {
  task_description: "<exact user sentence>",
}

This will allow your voice assistant to create tasks even if the keywords were missing.

📹 Video Guide

---

🗺️ Roadmap

Check the roadmap project to see and add your feature requests! ✍️

---

🚧 Limitations

• ❌ Cannot create new labels (except auto-creating voice)
• ❌ Cannot create new projects
• ❌ Cannot create new assignee users (only assign existing)
• ❌ Only works with one language at a time (selected Home Assistant language)

---

📜 License

MIT – see LICENSE.