vein

Agent-focused issue tracker built on Vikunja.

Setup

1. Create a Vikunja API token

In your Vikunja instance, go to Settings > API Tokens and create a token with these permissions:

vein init also needs projects (read_all) and projects_views (read_all) to discover your project and bucket IDs. You can add these temporarily or use a broader token for setup.

2. Configure environment

Set your Vikunja connection, then run vein init to discover project and bucket IDs:

export VIKUNJA_URL="https://your-vikunja-instance.example.com"
export VIKUNJA_API_TOKEN="tk_..."
vein init

Then set all the variables it prints:

export VIKUNJA_PROJECT_ID="1"
export VIKUNJA_VIEW_ID="10"
export VIKUNJA_TODO_BUCKET_ID="2"
export VIKUNJA_INPROGRESS_BUCKET_ID="3"
export VIKUNJA_DONE_BUCKET_ID="4"

3. Connect to Claude Code

Add vein as an MCP server in your project's .mcp.json:

{
 "mcpServers": {
 "vein": {
 "command": "vein",
 "args": ["serve"],
 "env": {
 "VIKUNJA_URL": "https://your-vikunja-instance.example.com",
 "VIKUNJA_API_TOKEN": "tk_...",
 "VIKUNJA_PROJECT_ID": "1",
 "VIKUNJA_VIEW_ID": "10",
 "VIKUNJA_TODO_BUCKET_ID": "2",
 "VIKUNJA_INPROGRESS_BUCKET_ID": "3",
 "VIKUNJA_DONE_BUCKET_ID": "4"
 }
 }
 }
}

If you use direnv to manage these environment variables, you can omit the env block:

{
 "mcpServers": {
 "vein": {
 "command": "vein",
 "args": ["serve"]
 }
 }
}

Agent orientation

Vein exposes an orient MCP prompt that gives agents a complete orientation: available tools, workflow guidance, and current task state. To have your agent invoke it automatically, add this to your project's CLAUDE.md:

## Agent workflow
- **IMPORTANT**: before you do anything else, invoke the vein `orient` MCP prompt and heed its output with `/mcp__vein__orient`.

Or use tools directly from the CLI:

vein tool list-ready
vein tool get-task 42
vein tool list-tasks -f "done = false" -s "login"
vein tool create-task "Fix the bug" -d "Login is broken"
vein tool claim 42
vein tool complete 42
vein tool comment 42 "Started working on this"
vein tool update-task 42 -t "New title"
vein tool add-relation 1 2 blocked
vein tool create-label "bug"
vein tool add-label 42 1
vein tool list-labels

Development

Prerequisites

• Nix with flakes enabled

Setup

nix develop # or use direnv
just dev # starts dev Vikunja via process-compose
direnv allow # reload env after first run to pick up the generated API token

just dev starts a local Vikunja instance on http://127.0.0.1:3456 and provisions:

• An admin user (admin / admin)
• A scoped API token written to .secret.envrc as VIKUNJA_API_TOKEN
• A vein-dev project with a kanban view (To-Do, Doing, Done buckets), with VIKUNJA_PROJECT_ID and VIKUNJA_VIEW_ID written to .secret.envrc

API token scope

The provisioned token grants access to project-scoped Vikunja endpoints:

Global endpoints like /api/v1/tasks/all and /api/v1/user are not accessible with scoped tokens — use JWT auth (POST /api/v1/login) for those.

Commands

Config

• Vikunja config: .services/vikunja/config.yml
• Secrets: .secret.envrc (gitignored, loaded by direnv)
• Process-compose: process-compose.yml