Setup

TaskMate setup

Walk the user through a working, verified configuration. CLI: uv run "${CLAUDE_PLUGIN_ROOT}/skills/taskmate/scripts/taskmate.py" ... (below: taskmate.py).

1. Assess

Run taskmate.py doctor. If a working profile already exists, say so and ask what they want: add another profile (e.g. a companion account next to their user account), change mode or persona, bind this repo to a project, or set up scheduled automations — then jump to that step.

2. Collect connection details

Ask the user (AskUserQuestion works well; one question at a time is kinder than a form):

1. Server URL — e.g. https://tasks.example.com (no /api/v1 suffix needed).
2. API token — created in the Vikunja web UI: avatar → Settings → API Tokens →

Create a token. Recommend granting all permissions the agent should have and warn that the token is shown only once. Never echo the full token back; mask it (tk_ab...ef).

1. Mode —

• user: the token belongs to the user's own account; the agent acts as them, silently.
• companion: the token belongs to a separate account for the agent. Requires someone to

register that account and share the relevant projects with it (read+write). If the account doesn't exist yet, guide them: register it in the Vikunja UI, log in as it once, create its API token, share projects via project → Share.

1. Persona (companion mode only) — the signing name. If they have no preference, offer a

couple of fitting suggestions with a wink and let them pick.

1. Timezone — IANA name (e.g. Europe/Berlin) so date filters resolve correctly.

3. Configure and verify

taskmate.py configure --url URL --token TOKEN --mode MODE [--persona NAME] [--timezone TZ] [--profile NAME] [--make-default]
taskmate.py doctor

configure validates against the live server before saving — on failure, fix URL/token and retry rather than saving broken config. Then show the user who they're connected as and how many projects are visible. In companion mode with zero visible projects, remind them to share projects with the companion account.

4. Offer the nice-to-haves (optional, don't push)

• Repo binding: if working inside a git repo, offer to create .claude/taskmate.local.md

(frontmatter: profile, project_id) pointing at one of their projects — list projects first so they can pick. Ensure the file is gitignored (it's personal config; add .claude/taskmate.local.md to .gitignore if needed).

• Automations: briefly present the schedulable pieces — /taskmate:pulse --quiet (daily

radar), /taskmate:auto groom|review|celebrate|unstick|triage — and set up whichever they want, per the scheduling recipes in ${CLAUDE_PLUGIN_ROOT}/skills/taskmate/references/integrations.md. Recommend starting with dry-runs.

5. Close the loop

Finish with a one-line summary (profile, account, mode, server, bound project if any) and one concrete next step, e.g. "try /taskmate:pulse". First impressions count: make this moment feel like meeting a great new coworker, not finishing a form.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: titusz
• Source: titusz/skills
• License: MIT

Install and usage instructions live in the source repository linked above.