# Project pack: Vikunja @ 5f9061d

Facts about **Vikunja** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Vikunja is a to-do app you own. Put tasks into projects, then see them as a simple list, a Kanban board, a table or a timeline. Add due dates, reminders, labels and repeating tasks, and share projects with family or friends. It syncs with phone calendars and can import from Todoist, Trello and Microsoft To Do. It runs on your own computer or server, so your plans stay private.

## Version and source
- Repository: https://github.com/go-vikunja/vikunja
- Pinned commit: `5f9061d4bdd1604a05eb3bb7506cecebdfbab917`. Use exactly this version.
- Get it: `git clone https://github.com/go-vikunja/vikunja vikunja && cd vikunja && git checkout 5f9061d4bdd1604a05eb3bb7506cecebdfbab917`
- Or download a zip: https://github.com/go-vikunja/vikunja/archive/5f9061d4bdd1604a05eb3bb7506cecebdfbab917.zip
- Official docs: https://vikunja.io/docs/
- Live demo: https://try.vikunja.io. Public demo run by the Vikunja team. Register a throwaway account and don't enter anything private.
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just your own household), you must offer them your source code under the same licence. Private use has no extra obligations. The desktop app folder is GPL-3.0-or-later. A few extra features for organisations (admin panel, time tracking, audit logs, user invites) need a paid licence key; everything else is free.

## Running it
- Easiest: docker run -d --name vikunja -p 3456:3456 -e VIKUNJA_SERVICE_PUBLICURL=http://localhost:3456/ -e VIKUNJA_SERVICE_SECRET=change-me-to-a-long-random-string -v vikunja-files:/app/vikunja/files -v vikunja-db:/db vikunja/vikunja # then open http://localhost:3456 and register
- Needs: Docker, or for development Go + Mage + Node.js + pnpm
- Develop: `mage build && ./vikunja   # API on :3456; in another terminal: cd frontend && pnpm install && pnpm dev (frontend on :4173)`
- Test: `mage test:web && mage test:feature && (cd frontend && pnpm test:unit)`
- Check/lint: `mage lint && (cd frontend && pnpm lint && pnpm typecheck)`
- Stack: go, typescript, vue, scss (Echo, xorm, Huma, Vue 3, Vite, Pinia, TanStack Query, Bulma). Difficulty for a non-developer with an AI: **moderate**. Registration, reminders, sharing, webhooks, CalDAV and imports are settings. Code changes touch a Go API and a Vue frontend that talks to it through a generated client. Upstream ships detailed AGENTS.md rules and skills.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`, `.agents/docs/`, `.agents/skills/`.

## Customisation points (settings → extend → code)
- **views-and-filters** [settings]: Make a "Today" or "This week" view, a chores board, or a filter for one person's tasks. → `Project views (List, Kanban, Table, Gantt; frontend/src/components/project/views/) and saved filters`
- **server-options** [settings]: Registration, reminders, link sharing, comments, attachments, time zone and your own logo. → `VIKUNJA_* environment variables or config.yml (all options listed in config-raw.json)`
- **sharing-and-teams** [settings]: Share a shopping list with a partner, or a chores project with the whole family. → `Project → Share (users, teams or a public link); teams in frontend/src/views/teams/`
- **webhooks-caldav-and-mcp** [extend]: Send task events anywhere, sync tasks to phone calendar apps, script with the API, or connect an AI assistant. → `User settings → Webhooks, CalDAV, API tokens and MCP (frontend/src/views/user/settings/)`
- **imports** [extend]: Move your existing tasks across in one go. → `Import page (pkg/modules/migration/ for Todoist, Trello, Microsoft To Do, TickTick, CSV and more)`
- **frontend** [code]: New screens, such as a big-text family chores board for a kitchen tablet. → `frontend/src/views/**, frontend/src/components/**, styles in frontend/src/styles/, text in frontend/src/i18n/lang/en.json`
- **backend** [code]: New data or behaviour. New routes go on /api/v2 only; database changes need a migration. → `pkg/models/ (data and permissions), pkg/routes/api/v2/ (new routes), pkg/migration/ (database changes)`

## Must keep working
- Existing projects, tasks, comments and attachments. Run a backup (vikunja dump) before changing code.
- Sharing permissions (users must only see projects shared with them).
- /api/v1 is frozen; new routes go on /api/v2. Don't hand-edit pkg/swagger/ or config.yml.sample, which are generated.
- Database changes need a migration in pkg/migration/ that works on SQLite, PostgreSQL and MySQL.
- The licence checks in pkg/license/; upstream asks you not to remove them.

## Staying updatable
Views, filters, sharing, webhooks, CalDAV, the API and the built-in MCP server cover most personal needs without a fork. For code, follow AGENTS.md and the skills in .agents/skills/; upstream welcomes AI-assisted contributions that follow those rules.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite file in the /db volume by default (PostgreSQL or MySQL optional); attachments in /app/vikunja/files. Back up the database and the files folder. The built-in vikunja dump command makes a full backup; each user can also export their own data from settings.
- Service: Email (SMTP) (optional, free with most providers): Task reminders, overdue summaries, invitations and password resets.
- Service: Unsplash (optional, free API key): Pretty photo backgrounds for projects.
- Service: Todoist, Trello or Microsoft To Do (optional, free): One-off import of your existing tasks.
- Setting `VIKUNJA_SERVICE_PUBLICURL`: The address you'll open Vikunja at (used in emails and links), e.g. https://tasks.example.org/.
- Setting `VIKUNJA_SERVICE_SECRET` (**secret**: the person enters it themselves, never in chat): Long random string used to sign logins. Set your own so logins survive restarts. Never paste it into an AI chat.
- Setting `VIKUNJA_SERVICE_ENABLEREGISTRATION`: Defaults to true. Set to false once your household has accounts.
- Setting `VIKUNJA_SERVICE_TIMEZONE`: Time zone for reminders (default GMT), e.g. Europe/London.
- Setting `VIKUNJA_SERVICE_CUSTOMLOGOURL`: Web address of your own logo. VIKUNJA_SERVICE_CUSTOMLOGOURLDARK sets one for dark mode.
- Setting `VIKUNJA_DATABASE_TYPE`: sqlite (default), postgres or mysql. VIKUNJA_DATABASE_* variables set the connection.
- Set your own VIKUNJA_SERVICE_SECRET, turn off registration after creating accounts, and use HTTPS before exposing it to the internet.
- Public share links let anyone with the link see the project. Use them only for things you don't mind being seen.
- Connecting an AI assistant through MCP or API tokens lets it read and change your tasks. Give it a token with only the access it needs.

---

# Customising Vikunja

Vikunja has a Go API and a Vue frontend, but **most household adaptations are settings**. Try levels 1 and 2 before touching code.

## Level 1: Settings (no code)
- **Views:** every project can have List, Kanban, Table and Gantt views. Add your own view with a filter, e.g. "Due this week" or "Tom's jobs".
- **Saved filters:** a filter across all projects that shows up like a project, e.g. "Everything due today".
- **Repeating tasks, reminders, labels and priorities** on each task.
- **Sharing:** share a project with a user, a team or a public link. Teams make it easy to share with the whole family.
- **Server options:** `VIKUNJA_*` environment variables or `config.yml`. Every option is listed in `config-raw.json`. Useful ones: `VIKUNJA_SERVICE_ENABLEREGISTRATION`, `VIKUNJA_SERVICE_TIMEZONE`, `VIKUNJA_SERVICE_CUSTOMLOGOURL`, the mailer settings, and daily overdue-task emails.
- **Language, time zone, default project and view, email and overdue reminders:** each user's General settings.

## Level 2: Extend (no fork)
- **Webhooks** (user settings and per project): send task events, such as "task done", to n8n, Home Assistant or a small script that posts to Telegram.
- **CalDAV** (user settings → CalDAV): sync tasks with phone and desktop calendar apps.
- **API tokens** and the REST API at `/api/v2` (docs at `/api/v2/docs` on your instance).
- **MCP** (user settings → MCP): connect an AI assistant that can read and manage your tasks.
- **Imports:** Todoist, Trello, Microsoft To Do, TickTick, CSV and more (`pkg/modules/migration/`).
- **Plugins:** server plugins (see `examples/plugins/example/` and `pkg/plugins/`).

## Level 3: Code
Read upstream `AGENTS.md` and `.agents/docs/` first. They are detailed, and include skills for common changes.

| Change | Where |
|---|---|
| New page or view | `frontend/src/views/**`, components in `frontend/src/components/**` |
| Project views (list, board, table, Gantt) | `frontend/src/components/project/views/` |
| Calling the API from the frontend | the generated client in `frontend/src/client/generated` and queries in `frontend/src/client/queries` only |
| Styles | `frontend/src/styles/` |
| Text | `frontend/src/i18n/lang/en.json` |
| New data | `pkg/models/` (use the `crudable` skill) + a migration via `mage dev:make-migration` (`pkg/migration/`) |
| New endpoint | `pkg/routes/api/v2/` only; `/api/v1` is frozen |

## Running locally
- **Just use it:** `docker run -d -p 3456:3456 -e VIKUNJA_SERVICE_PUBLICURL=http://localhost:3456/ -v vikunja-files:/app/vikunja/files -v vikunja-db:/db vikunja/vikunja`, then open http://localhost:3456 and register.
- **Develop:**
  1. Install Go, Mage, Node.js and pnpm.
  2. Build and run the API with `mage build && ./vikunja` (port 3456).
  3. In another terminal: `cd frontend && pnpm install && pnpm dev`.
  4. Open http://localhost:4173.
- **Check:** `mage lint`, `mage test:web`, `mage test:feature`, and in `frontend/`: `pnpm lint`, `pnpm typecheck`, `pnpm test:unit`. Plain `go test` does not work here.

## Pitfalls
- Back up first with `vikunja dump`. Tasks and attachments are personal data.
- Never hand-edit `pkg/swagger/` or `config.yml.sample`; they are generated.
- Migrations must work on SQLite, PostgreSQL and MySQL.
- Public share links are open to anyone with the link.
- Upstream asks you not to remove the licence checks in `pkg/license/`. They only affect a few organisation features.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/vikunja/5f9061d/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/vikunja/5f9061d/SKILL.md)