---

name: vikunja description: Manage tasks and projects on a self-hosted Vikunja instance (PERSONAL/WORK). Use when the user wants to create, view, complete, or manage tasks, check what's due or overdue, list projects, or get notifications. Always register user-requested tasks in Vikunja for tracking and follow-up.

Vikunja Task Manager (PERSONAL / WORK)

Gestiona tareas y proyectos en una instancia self-hosted de Vikunja mediante REST API.

Skill Files

| File | Description | |------|-------------| | SKILL.md (this file) | Command reference and API documentation | | REGISTER.md | Initial setup and configuration | | HEARTBEAT.md | Periodic routine to enforce task tracking |

Install locally:

mkdir -p ~/.nimworker/skills
curl -s https://hiveagilectl.sh/skill.md > ~/.nimworker/skills/SKILL.md
curl -s https://hiveagilectl.sh/register.md > ~/.nimworker/skills/REGISTER.md
curl -s https://hiveagilectl.sh/heartbeat.md > ~/.nimworker/skills/HEARTBEAT.md

Or copy from local repo:

mkdir -p ~/.nimworker/skills
cp ~/work/taskworker/skill/SKILL.md ~/.nimworker/skills/
cp ~/work/taskworker/REGISTER.md ~/.nimworker/skills/
cp ~/work/taskworker/HEARTBEAT.md ~/.nimworker/skills/

---

Complete Command Reference (28 commands)

| Category | Command | Description | |----------|---------|-------------| | Tasks | tasks | List tasks with filters (project, assignee, search, etc.) | | | search | Search tasks across all projects by keyword | | | task | Get detailed task information | | | create-task | Create new task with description, priority, due date | | | edit-task | Edit task title, description, priority, due date | | | delete-task | Delete a task | | | complete | Mark task as done | | | move-task | Move task to different stage/bucket | | | assign-task | Assign task to user (supports multiple assignees) | | | overdue | Show overdue tasks | | | due | Show tasks due soon (default 24h) | | Labels | labels | List all labels | | | add-label | Add label to task (auto-creates if needed) | | | remove-label | Remove label from task | | Comments | comments | List comments on a task | | | add-comment | Add comment to task | | Projects | projects | List all projects | | | create-project | Create new project (auto-creates 5 Kanban stages) | | | buckets / stages | List Kanban stages in project | | | create-bucket / create-stage | Create new Kanban stage | | Teams | teams | List all teams with members | | | create-team | Create new team | | | share-project | Share project with team | | | project-teams | List teams in a project | | Users | users | List users in a project | | | invite-user | Invite user to project (read/write/admin) | | Other | notifications | Show notifications |

Key Features:

• ✅ Filter by assignee: --assign "username" to see only tasks assigned to specific user
• ✅ Auto-stage creation: New projects get 5 default Kanban stages (Backlog, To Do, In Progress, Review, Done)
• ✅ Multiple assignees: Tasks can be assigned to multiple users
• ✅ Auto-label creation: Adding non-existent labels creates them automatically
• ✅ Rich output: Shows project names, stage names with emojis, assignees, due dates, priorities
• ✅ Team collaboration: Share projects with teams, manage user permissions

---

Register First

Before using Vikunja, you must configure it. See REGISTER.md for full setup.

Quick start:

export VIKUNJA_URL="https://your-vikunja-instance.com"
export VIKUNJA_TOKEN="your-api-token"
export VIKUNJA_TZ="Europe/Rome"
export VIKUNJA_BOT_USERNAME="Jarvis"  # Tu username en Vikunja

# Bootstrap default projects
~/.nimworker/vikunja.py ensure-default-projects

IMPORTANTE: Configura VIKUNJA_BOT_USERNAME con tu nombre de usuario en Vikunja. Este username se usa para:

• Asignar tareas al bot
• Filtrar tareas del bot (--assign "Jarvis")
• Ejecución autónoma de tareas (ver HEARTBEAT.md)

---

Set Up Your Heartbeat 💓

Critical: Without the heartbeat, tasks won't be tracked consistently.

See HEARTBEAT.md for the full routine. The heartbeat ensures:

• ✅ Every task request is registered in Vikunja
• ✅ Overdue tasks are checked regularly
• ✅ No tasks are forgotten

---

Principios de uso (obligatorios)

1. Fuente de verdad: si el usuario pide una "tarea", se crea en Vikunja (siempre).
2. Sólo dos proyectos base: PERSONAL y WORK.
3. Seguimiento: cualquier consulta de "qué queda / vencimientos / atrasos / cómo voy" se responde consultando Vikunja (overdue, due, tasks).
4. Cierre: cuando el usuario diga "hecho / completado / listo", se completa la tarea correspondiente en Vikunja.

---

Setup

Configura variables de entorno:

export VIKUNJA_URL="https://your-vikunja-instance.com"
export VIKUNJA_TOKEN="your-api-token"

# Timezone para filtros (recomendado)
export VIKUNJA_TZ="Europe/Rome"

# Proyectos base (siempre estos dos)
export VIKUNJA_PROJECT_PERSONAL="PERSONAL"
export VIKUNJA_PROJECT_WORK="WORK"

# IMPORTANTE: Nombre de usuario del bot en Vikunja (para asignación de tareas)
export VIKUNJA_BOT_USERNAME="Jarvis"  # Cambia esto por tu username en Vikunja

Configuración del usuario/bot:

1. Token: Vikunja → Settings → API Tokens → Create token
2. Username: El nombre de usuario que usas en Vikunja (ej: "Jarvis", "Aitor", "Bot")
   • Este username se usa para asignar tareas al bot
   • El bot ejecutará automáticamente tareas asignadas a este usuario
   • Configúralo en VIKUNJA_BOT_USERNAME

Recomendación: ejecutar una vez ensure-default-projects para crear PERSONAL/WORK si faltan.

---

Enrutado de tareas a PERSONAL / WORK (sin preguntar)

Si el usuario no especifica proyecto explícito, se asigna así:

• WORK si aparecen señales de trabajo: cliente, reunión, entrega, deploy, factura, empresa, proyecto, ticket, incidencia, call, oferta, presupuesto.
• PERSONAL si aparecen señales personales: casa, compra, familia, salud, viaje, médico, gym, pago personal.
• Si no está claro: PERSONAL por defecto.

El usuario puede forzar: "en WORK …" / "en PERSONAL …".

---

Metodología recomendada (ligera)

• Daily (2 min): overdue + due 24h para WORK y PERSONAL.
• Weekly (10 min): revisar lista por prioridad y limpiar/ajustar.

---

Commands

Base: ~/.nimworker/vikunja.py (Python wrapper) o ~/.nimworker/scripts/vikunja.sh (Bash script)

Bootstrap: asegurar proyectos base

~/.nimworker/vikunja.py ensure-default-projects

List tasks

~/.nimworker/vikunja.py tasks --count 10
~/.nimworker/vikunja.py tasks --project "WORK" --count 20
~/.nimworker/vikunja.py tasks --project "PERSONAL" --count 20
~/.nimworker/vikunja.py tasks --search "groceries"
~/.nimworker/vikunja.py tasks --sort priority --order desc

Output includes:

• ✅ Project name (WORK, PERSONAL)
• ✅ Stage/Bucket name (📋 Backlog, 📝 To Do, 🔄 In Progress, 👀 Review, ✅ Done)
• ✅ Assigned users (if any)
• ✅ Due date and priority

Filter by assignee (NEW! ✨)

# Show only tasks assigned to specific user
~/.nimworker/vikunja.py tasks --assign "Aitor"
~/.nimworker/vikunja.py tasks --assign "Jarvis" --count 20

# Combine with project filter
~/.nimworker/vikunja.py tasks --project "WORK" --assign "Aitor"

# Combine with other filters
~/.nimworker/vikunja.py tasks --assign "Aitor" --sort priority --order desc

Filtrado avanzado (Vikunja filters)

~/.nimworker/vikunja.py tasks --filter 'done = false && priority >= 3'
~/.nimworker/vikunja.py tasks --project "WORK" --filter 'priority >= 4'

Overdue tasks

~/.nimworker/vikunja.py overdue
~/.nimworker/vikunja.py overdue --project "WORK"
~/.nimworker/vikunja.py overdue --project "PERSONAL"

Tasks due soon (next N hours)

~/.nimworker/vikunja.py due --hours 24
~/.nimworker/vikunja.py due --hours 24 --project "WORK"
~/.nimworker/vikunja.py due --hours 48 --project "PERSONAL"

Create a task

Basic task:

~/.nimworker/vikunja.py create-task --project "WORK" --title "Llamar a cliente X" --due "2026-02-01" --priority 4
~/.nimworker/vikunja.py create-task --project "PERSONAL" --title "Comprar leche" --due "2026-02-01" --priority 2

Task with detailed description:

~/.nimworker/vikunja.py create-task \
  --project "WORK" \
  --title "Implementar autenticación OAuth" \
  --description "Integrar OAuth 2.0 con Google y GitHub. Requisitos: tokens JWT, refresh tokens, manejo de errores. Ver documentación en /docs/auth.md" \
  --due "2026-02-15" \
  --priority 5 \
  --bucket "To Do"

Task with multiline description:

~/.nimworker/vikunja.py create-task \
  --project "PERSONAL" \
  --title "Planificar viaje a Barcelona" \
  --description "Tareas:
- Reservar vuelos (Vueling o Ryanair)
- Hotel cerca de Las Ramblas
- Entradas Sagrada Familia
- Restaurantes recomendados: El Xampanyet, Can Culleretes
Presupuesto: 800€" \
  --due "2026-03-01" \
  --priority 3

Assign to a specific Kanban stage:

~/.nimworker/vikunja.py create-task --project "WORK" --title "Fix bug #123" --bucket "In Progress" --priority 5
~/.nimworker/vikunja.py create-task --project "WORK" --title "New feature" --stage "To Do" --priority 3

Parameters:

• --title: Task title (required)
• --project: Project name (required)
• --description: Detailed description (optional, supports multiline)
• --due: Due date in YYYY-MM-DD format
• --priority: 1 (low) to 5 (urgent)
• --bucket / --stage: Kanban stage (partial match, e.g., "todo", "progress", "done")

Complete a task

~/.nimworker/vikunja.py complete --id 123

Get task details

~/.nimworker/vikunja.py task --id 123

List projects

~/.nimworker/vikunja.py projects

Create a project (extra)

Nota: El flujo principal usa PERSONAL y WORK. Crear proyectos adicionales sólo si el usuario lo pide explícitamente.

~/.nimworker/vikunja.py create-project --title "New Project" --description "Optional description"

Automatic Kanban stages: When creating a project, 5 default stages are automatically created:

• 📋 Backlog - Ideas and future tasks
• 📝 To Do - Ready to start
• 🔄 In Progress - Currently working on
• 👀 Review - Waiting for review/approval
• ✅ Done - Completed tasks

To skip automatic stage creation, use --no-stages:

~/.nimworker/vikunja.py create-project --title "New Project" --no-stages

Get notifications

~/.nimworker/vikunja.py notifications

Assign tasks to users

# Assign task to a user
~/.nimworker/vikunja.py assign-task --id 123 --user "Aitor"
~/.nimworker/vikunja.py assign-task --id 456 --user "Jarvis"

# Note: Users must be in project teams or directly invited to the project
# Tasks can have multiple assignees

Move tasks between stages

# Move task to different Kanban stage
~/.nimworker/vikunja.py move-task --id 123 --stage "In Progress"
~/.nimworker/vikunja.py move-task --id 456 --bucket "Done"
~/.nimworker/vikunja.py move-task --id 789 --stage "Review" --project "WORK"

Edit tasks

# Edit task details
~/.nimworker/vikunja.py edit-task --id 123 --title "New title"
~/.nimworker/vikunja.py edit-task --id 123 --priority 5 --due "2026-03-01"
~/.nimworker/vikunja.py edit-task --id 123 --description "Updated description"

Delete tasks

~/.nimworker/vikunja.py delete-task --id 123

Labels

# List all labels
~/.nimworker/vikunja.py labels

# Add label to task (creates label if it doesn't exist)
~/.nimworker/vikunja.py add-label --id 123 --label "urgent"
~/.nimworker/vikunja.py add-label --id 123 --label "bug"

# Remove label from task
~/.nimworker/vikunja.py remove-label --id 123 --label "urgent"

Comments

# List comments on a task
~/.nimworker/vikunja.py comments --id 123

# Add comment to task
~/.nimworker/vikunja.py add-comment --id 123 --comment "Working on this now"
~/.nimworker/vikunja.py add-comment --id 456 --comment "Blocked by task #123"

Team Management

# List all teams
~/.nimworker/vikunja.py teams

# Create a new team
~/.nimworker/vikunja.py create-team --name "Development Team" --description "Core dev team"

# Share project with team
~/.nimworker/vikunja.py share-project --project "WORK" --team "Development Team" --rights write

# List teams in a project
~/.nimworker/vikunja.py project-teams --project "WORK"

User Management

# List users in a project
~/.nimworker/vikunja.py users --project "WORK"

# Invite user to project
~/.nimworker/vikunja.py invite-user --project "WORK" --user "maria@example.com" --rights write
~/.nimworker/vikunja.py invite-user --project "PERSONAL" --user "john" --rights read

Rights levels:

• read - Can view tasks
• write - Can create and edit tasks
• admin - Full project administration

Kanban Stages (Buckets)

# List stages in a project
~/.nimworker/vikunja.py buckets --project "WORK"
~/.nimworker/vikunja.py stages --project "PERSONAL"  # alias

# Create a new stage
~/.nimworker/vikunja.py create-bucket --project "WORK" --title "🔥 Urgent" --position 0
~/.nimworker/vikunja.py create-stage --project "WORK" --title "🧪 Testing"  # alias

Search across all projects

# Search by keyword in title or description
~/.nimworker/vikunja.py search --query "bug"
~/.nimworker/vikunja.py search --query "cliente"
~/.nimworker/vikunja.py search --query "payment"

Search output includes:

• Project name
• Stage name
• Due date and priority
• Task ID

---

Rutinas listas para copiar

Daily (mañana)

# Check overdue and upcoming tasks
~/.nimworker/vikunja.py overdue --project "WORK"
~/.nimworker/vikunja.py due --hours 24 --project "WORK"
~/.nimworker/vikunja.py overdue --project "PERSONAL"
~/.nimworker/vikunja.py due --hours 24 --project "PERSONAL"

# Check your assigned tasks
~/.nimworker/vikunja.py tasks --assign "YourUsername" --count 10

Weekly (revisión)

# Review all tasks by priority
~/.nimworker/vikunja.py tasks --project "WORK" --sort priority --order desc --count 50
~/.nimworker/vikunja.py tasks --project "PERSONAL" --sort priority --order desc --count 50

# Review team assignments
~/.nimworker/vikunja.py tasks --project "WORK" --assign "Aitor"
~/.nimworker/vikunja.py tasks --project "WORK" --assign "Jarvis"

---

Due Date Monitoring (cron genérico)

Ejemplo simple (sin acoplar a bots):

# Cada día a las 09:00
0 9 * * * ~/work/taskworker/vikunja overdue && ~/work/taskworker/vikunja due --hours 24

Si querés notificaciones, integralo con tu sistema (Telegram, email, etc.) según tu stack.

---

Notes

• Los nombres de proyecto en --project son case-insensitive.
• Filters siguen la sintaxis de filtros de Vikunja.
• Timezone para filtros se controla con VIKUNJA_TZ (por defecto recomendado: Europe/Rome).

---

Examples

Work Tasks

Development task with details:

~/work/taskworker/vikunja.py \
  --project "WORK" \
  --title "Implementar API de pagos" \
  --description "OBJETIVO: Integrar Stripe para pagos recurrentes

REQUISITOS:
- Webhook para eventos de pago
- Manejo de errores y reintentos
- Tests unitarios y de integración
- Documentación en Swagger

REFERENCIAS:
- Docs Stripe: https://stripe.com/docs/api
- Ticket Jira: PROJ-123

ESTIMACIÓN: 40 horas" \
  --due "2026-02-20" \
  --priority 5 \
  --bucket "To Do"

Bug fix:

~/work/taskworker/vikunja.py \
  --project "WORK" \
  --title "Fix: Login timeout en producción" \
  --description "PROBLEMA: Usuarios reportan timeout al hacer login después de 5 minutos

PASOS PARA REPRODUCIR:
1. Login en app
2. Esperar 5+ minutos sin actividad
3. Intentar hacer cualquier acción
4. Error: 401 Unauthorized

CAUSA POSIBLE: JWT expira pero refresh token no se usa correctamente

LOGS: /var/log/app/auth-errors.log
REPORTADO POR: 3 usuarios (tickets #456, #457, #458)" \
  --due "2026-02-05" \
  --priority 5 \
  --bucket "In Progress"

Client communication:

~/work/taskworker/vikunja.py \
  --project "WORK" \
  --title "Enviar propuesta a cliente Acme Corp" \
  --description "SOLICITUD: Cotización para desarrollo app móvil

ALCANCE:
- App móvil iOS/Android
- Backend API REST
- Panel admin web
- Integración con su ERP

ESTIMACIÓN: 3 meses, 2 devs full-time
PRESUPUESTO: 45.000€

CONTACTO: Juan Pérez (juan@acmecorp.com)
TEMPLATE: /templates/propuesta-desarrollo.docx" \
  --due "2026-02-10" \
  --priority 4 \
  --bucket "To Do"

Personal Tasks

Shopping list:

~/work/taskworker/vikunja.py \
  --project "PERSONAL" \
  --title "Compra semanal supermercado" \
  --description "LISTA DE COMPRAS:

FRESCOS:
- Leche (2L)
- Pan integral
- Frutas: manzanas, plátanos, naranjas
- Verduras: lechuga, tomates, pepino

DESPENSA:
- Pasta (500g)
- Arroz (1kg)
- Aceite de oliva
- Conservas: atún, tomate

LIMPIEZA:
- Detergente lavadora
- Papel higiénico

PRESUPUESTO: ~60€
SUPERMERCADO: Mercadona o Carrefour" \
  --due "2026-02-02" \
  --priority 3 \
  --bucket "To Do"

Travel planning:

~/work/taskworker/vikunja.py \
  --project "PERSONAL" \
  --title "Organizar viaje a Japón (abril)" \
  --description "VIAJE: 15-30 abril (15 días)

PENDIENTE:
- Vuelos Madrid-Tokyo (Skyscanner)
- JR Pass (7 días, ~280€)
- Hoteles: Tokyo (5n), Kyoto (4n), Osaka (3n)
- Pocket WiFi o SIM card
- Seguro de viaje

LUGARES A VISITAR:
- Senso-ji, Fushimi Inari, Dotonbori, Nara

PRESUPUESTO: ~2.500€/persona
COMPAÑEROS: Ana y Carlos

GUÍAS: japan-guide.com, /r/JapanTravel" \
  --due "2026-03-01" \
  --priority 2 \
  --bucket "Backlog"

Health appointment:

~/work/taskworker/vikunja.py \
  --project "PERSONAL" \
  --title "Cita médico: revisión anual" \
  --description "CITA: 12 febrero, 10:30
LUGAR: Centro Médico Salud, C/ Mayor 45, 3º
TELÉFONO: 91-234-5678

LLEVAR:
- Tarjeta sanitaria
- Resultados análisis sangre
- Lista medicación actual

TEMAS A CONSULTAR:
- Dolor espalda recurrente
- Renovar receta medicación presión arterial
- Vacuna gripe

RECORDATORIO: Llegar 10 min antes" \
  --due "2026-02-12" \
  --priority 4 \
  --bucket "To Do"

---

Next Steps

1. Setup: Read REGISTER.md for initial configuration
2. Heartbeat: Read HEARTBEAT.md to set up periodic checks
3. Start using: Create your first task and test the workflow

Remember: Vikunja is your source of truth. If a task isn't in Vikunja, it doesn't exist. 📋