Vikunja Kanban

Manage Vikunja kanban boards via API to read, create, move, and complete tasks across predefined buckets with integrated cron sync.

Security Scan

The skill generally matches a Vikunja kanban helper, but it has several inconsistencies and risky choices — notably a hardcoded external URL, an undeclared long-lived API token requirement, and instructions that recommend direct DB changes — so review and fix before installing.

Purpose & Capability

The scripts and SKILL.md implement expected kanban actions (list/create/move/complete). However metadata claims no required env vars/credentials while every script requires a VIKUNJA_TOKEN. Also the scripts hardcode VIKUNJA_URL to https://kanban.pigpen.haus instead of using a configurable URL as the documentation implies. These mismatches between declared requirements and actual behavior are problematic.

Instruction Scope

Runtime instructions tell the agent to run included shell scripts which call the Vikunja API — this is within scope. But SKILL.md also recommends a direct PostgreSQL workaround (UPDATE users_projects ...) to change permissions, which requires database access outside the kanban API surface and is beyond typical skill scope. The skill also documents storing credentials in secrets/vikunja.env but does not declare them in metadata.

Install Mechanism

This is an instruction-only skill with bundled shell scripts; there is no install spec, no downloads, and nothing will be written to disk by an installer beyond the provided files. Risk from install mechanism itself is low.

Credentials

The scripts require a long-lived VIKUNJA_TOKEN with broad tasks+projects permissions (read_all, update, create, delete). That level of access is functionally sufficient for the described operations but is high privilege and long-lived (expires 2030). Metadata fails to declare this required credential and the scripts hardcode VIKUNJA_URL to a third-party host, which could expose that token to an external service you may not control.

Persistence & Privilege

The skill is not always-enabled and does not request persistent system privileges or modify other skills/configs. It does not perform autonomous or background persistence beyond using the provided scripts.

What to consider before installing

Before installing or using this skill: - Treat the VIKUNJA_TOKEN as sensitive. The scripts expect it but the registry metadata does not declare it — the token is long-lived and has wide permissions. Create a least-privilege token (narrow permissions, shorter expiry) and do not reuse high-privilege tokens. - Inspect and update the scripts to point VIKUNJA_URL to your own Vikunja instance (the included scripts currently hardcode https://kanban.pigpen.haus). Do not use that remote host unless you explicitly trust and control it. - Remove any hardcoded identifiers (PROJECT_ID, VIEW_ID, BUCKET IDs) or confirm they match your environment. Hardcoded IDs may perform operations in an unintended project. - Avoid storing the token in the repository. Keep secrets/vikunja.env locally in a secure secrets store and ensure it’s gitignored. - The SKILL.md suggests editing the PostgreSQL DB to change permissions — this is an out-of-band, high-risk operation. Prefer using the API or proper admin procedures; do not run SQL provided by third-party skills unless you fully trust the source and understand the DB schema and implications. - If you need stronger assurance, ask the publisher for: (1) an explanation why metadata omits required env vars, (2) a configurable script variant that reads VIKUNJA_URL from env, and (3) confirmation who controls kanban.pigpen.haus. Without those fixes, treat the skill as suspicious and do not supply production credentials.

Vikunja Kanban Skill

Manage a Vikunja kanban board via API. Read status, create/move/complete tasks, and integrate with heartbeat and triage crons.

Config

Credentials stored in secrets/vikunja.env:

VIKUNJA_URL=https://your-vikunja-instance
VIKUNJA_TOKEN=${VIKUNJA_TOKEN}
VIKUNJA_PROJECT_ID=1
VIKUNJA_VIEW_ID=4

Authentication

All scripts use a long-lived API token (expires 2030-01-01). No JWT login needed.

• Permissions: tasks (read_all, update, create, delete), projects (read_all, update, create)
• JWT login credentials kept in secrets/vikunja.env for reference only

Bucket IDs

ID	Name	Purpose
1	🔴 Urgent	Needs immediate attention
2	⏳ Waiting On	Sent/requested, awaiting reply
7	⚠️ System Issues	Infra/system problems
8	🚧 Active Projects	In progress
9	📅 Upcoming	Scheduled/future
10	📥 Inbox	New items, untriaged
3	✅ Done	Completed

Scripts

All scripts are in the skill's scripts/ directory. Run from the skill root.

Read the board

bash scripts/vikunja-status.sh              # All buckets
bash scripts/vikunja-status.sh "Urgent"     # Filter by bucket name

Add a task

bash scripts/vikunja-add-task.sh "Title" "Description" BUCKET_ID [PRIORITY]
# Priority: 0=unset, 1=low, 2=medium, 3=high, 4=urgent
# Example: bash scripts/vikunja-add-task.sh "Fix DNS" "Check records" 1 4

Move a task between buckets

bash scripts/vikunja-move-task.sh TASK_ID BUCKET_ID
# Example: bash scripts/vikunja-move-task.sh 15 3  # Move to Done

Complete a task

bash scripts/vikunja-complete-task.sh TASK_ID

Heartbeat Integration

The heartbeat cron reads from Vikunja:

bash scripts/vikunja-status.sh

• Check 🔴 Urgent for items aging >1h
• If Vikunja unreachable, fall back to scripts/nc-status-board.sh read

Email Triage Integration

Email triage adds Action Required items to the Inbox bucket:

bash scripts/vikunja-add-task.sh "Email subject" "Brief description" 10 3

API Reference

• Base URL: https://your-vikunja-instance/api/v1
• Auth: POST /login with username/password → JWT token (short-lived)
• Tasks: PUT /projects/{id}/tasks (create), POST /tasks/{id} (update)
• Buckets: POST /projects/{id}/views/{view}/buckets/{bucket}/tasks (move task)
• Views: GET /projects/{id}/views/{view}/tasks (list tasks by bucket)
• Projects: POST /projects/{id} (update title/settings), GET /projects (list all)
• Sharing: PUT /projects/{id}/users {"username":"...", "right":N} (add user)
• Users: GET /users?s=query (search), POST /user/password (self-service password change)

Known API Bugs & Gotchas

Sharing permissions ignored on creation

PUT /projects/{id}/users ignores the right field — always creates with permission=0 (read-only). Workaround: Set permission directly in PostgreSQL:

UPDATE users_projects SET permission = 2 WHERE user_id = X AND project_id = Y;

Permission values: 0=read-only, 1=read+write, 2=admin

Default Inbox project cannot be deleted

Every new user gets an auto-created "Inbox" project. DELETE /projects/{id} returns error 3012. Workaround: Rename it: POST /projects/{id} with {"title":"New Name"}

Password change is self-service only

No admin endpoint to change another user's password. Must login as the target user: POST /api/v1/user/password with {"old_password":"...", "new_password":"..."}

API token creation needs both tasks AND projects permissions

Tokens with only tasks permissions cannot read kanban views (returns 401). Must include: "permissions":{"tasks":["read_all","update","create","delete"],"projects":["read_all","update","create"]}

Token creation endpoint

PUT /api/v1/tokens to create, GET /api/v1/tokens to list, DELETE /api/v1/tokens/{id} to remove. Required fields: title, expires_at (ISO-8601), permissions (object with permission groups).

Notes

• Long-lived API token used (expires 2030) — no JWT login overhead
• Vikunja uses PUT for creation, POST for updates (unusual)
• Bucket IDs are specific to the Kanban view (view_id=4)
• Project name: "Kit Operations" (renamed from default "Inbox")
• Project shared: Kit (id:1, admin/owner), Alex (id:2, admin via DB fix)
• Token has tasks + projects permissions; covers all kanban operations
• Each user gets a default project that can't be deleted — rename to avoid confusion