vikunja

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 "[e-mail]" --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 ([e-mail])
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. 📋