🎙️ Vikunja Voice Assistant for Home Assistant

Say “create a task” or “add a task” → Your task goes straight into Vikunja!

Video Demo 🎥

⚠️ Important Notice: With recent changes to Vikunja's API permissions (from version 2.3.0+), you must ensure your API token includes the correct permissions listed below. Missing permissions may prevent label attachment and assignment from working properly.

---

✨ 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!

1. In HACS → Search: Vikunja Voice Assistant → Install

2. Restart Home Assistant

3. Go to Settings → Devices & Services → Add Integration

4. Search: Vikunja Voice Assistant

5. 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
     • Tasks Assignees: Create
     • Tasks Labels: Create

   • 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

6. ✅ 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.