vikunja-agents/AGENT-ONBOARDING.md

Vikunja access — agent onboarding prompt

Hand the block below to any agent that needs Vikunja access. It is written to be pasted verbatim as a task prompt. Everything after the --- is the prompt.

Before pasting, substitute:

• <AGENT_NAME> — the bot account for this harness, e.g. bot-nullclaw
• <HARNESS> — claude-code, omp, picocode, or other

---

Task: configure your own Vikunja access

You are <AGENT_NAME>. Give yourself working access to Vikunja at https://todo.dominat.us, then verify it and report what you can and cannot see.

Facts you need

• Tooling lives at /srv/pods/vikunja-agents/ on reptar: vk (CLI), vkclient.py (shared client), vikunja_mcp.py (MCP server, stdio). Standard-library Python only — no virtualenv, no pip install.
• If you are not on reptar, copy those three files to the machine you run on (~/opt/vikunja-agents/) and symlink vk onto your PATH.
• Auth is a Vikunja API token, read from ~/.config/vikunja-agents/config.json (mode 0600) or $VIKUNJA_TOKEN. Select an identity with $VIKUNJA_PROFILE.
• Your account must already exist. The normal shape is a bot user: a local account owned by a human, with no password of its own. If it does not exist, stop and ask — creating one is your owner's job (Vikunja UI: Settings → Bot Users). MAS/OIDC accounts cannot be used for this (see constraints).

Step 1 — get your token (once)

If your account is a bot user (the normal case — it has an owner and no password), you cannot mint your own token: token creation needs a password login and bots have none. Your owner mints it for you, then hands it over out of band. Store it without putting it in argv or shell history:

vk profile <AGENT_NAME> --username <AGENT_NAME> < /path/to/token-file
# or:  pbpaste | vk profile <AGENT_NAME> --username <AGENT_NAME>

vk profile verifies the token against the API before saving, so a bad paste fails loudly instead of silently writing a dead profile. It lands in ~/.config/vikunja-agents/config.json at mode 0600.

If you have no token, stop and ask your owner for one. They create it from Vikunja's UI (Settings → API tokens, issued for your bot) or with an authenticated PUT /api/v1/tokens carrying owner_id: <your user id>.

If your account is instead a plain user with a password (legacy), you can mint your own:

VIKUNJA_PASSWORD="$(cat ~/.config/vikunja-agents/<AGENT_NAME>.password)" \
  vk bootstrap --username <AGENT_NAME> --title "<HARNESS> ($(hostname))"

Either way: never echo the token, paste it into a chat, or commit it. It expires in a year and cannot renew itself — renewal means asking your owner again.

Step 2 — register the MCP server for your harness

claude-code:

claude mcp add vikunja -e VIKUNJA_PROFILE=<AGENT_NAME> -- /srv/pods/vikunja-agents/vikunja_mcp.py

omp — add to ~/.omp/agent/mcp.json (create it if absent):

{
  "mcpServers": {
    "vikunja": {
      "type": "stdio",
      "command": "/srv/pods/vikunja-agents/vikunja_mcp.py",
      "env": { "VIKUNJA_PROFILE": "<AGENT_NAME>" }
    }
  }
}

picocode — add to picocode.yaml:

mcp:
  vikunja:
    command: /srv/pods/vikunja-agents/vikunja_mcp.py
    env:
      VIKUNJA_PROFILE: <AGENT_NAME>
    auto_allow:
      - "^vikunja_list_"
      - "^vikunja_get_"

other — the server speaks MCP over stdio (JSON-RPC 2.0, newline-delimited). Run /srv/pods/vikunja-agents/vikunja_mcp.py with VIKUNJA_PROFILE set. If your harness cannot speak MCP, skip this step and use the vk CLI instead; it covers the same ground.

Step 3 — verify, and do not skip this

vk whoami          # must print <AGENT_NAME>
vk projects        # the projects you can actually see
vk tasks --mine    # your queue

Then confirm the MCP path independently of the CLI — restart your harness if it binds MCP servers at startup (claude-code does), and call vikunja_list_projects. If the tool is missing, the registration did not take; if it errors, the token did not take. These are different failures — do not report one as the other.

Step 4 — report

State plainly:

1. Which projects you can see (likely only your own Inbox — see constraints).
2. Whether MCP tools are available, or whether you fell back to the CLI.
3. Anything you had to ask a human for.

Constraints that will otherwise cost you an hour

• A token cannot mint another token. Vikunja excludes the tokens route group from anything an API token can be granted. For a bot user that means only your owner can issue or renew your token; you can never do it yourself, and there is no password you could use even if you wanted to.
• You cannot ask the API who you are. /user is unreachable with a token (user_* routes are excluded too). vk whoami reads the username from your config file. Do not try to fix a 401 on /user — it is expected.
• You start with only your own Inbox. A new account sees nothing else until a human shares projects with it. If vk projects shows one project, that is normal, not a broken token — say so and ask for the shares you need.
• Assignment is dispatch. Work reaches you by being assigned to <AGENT_NAME>. Use vk tasks --mine. Do not scrape other agents' queues.
• Username lookup is project-scoped. Resolving a username to an id uses /projects/{id}/projectusers; the instance-wide /users search is not grantable to tokens. You can only assign to users who can access that project.
• Updates replace the whole task. The client merges for you; if you call the API directly, read-modify-write or you will blank fields.
• Link your work back. Put VK-<task id> in commit messages, and fixes VK-<id> to close a task on push — a Gitea bridge posts the commit link onto the task. Without it a task says "done" but never says what changed.

Rules

• One account per harness. Do not share a profile with another agent — separate accounts are what make the task history say who did what.
• Never print, log, or transmit the token or password. If you think one leaked, say so immediately; rotation needs a human.
• Comment on tasks when you finish work, find something that changes scope, or are blocked. Do not narrate routine steps.