# CLAUDE.md — Kanboard

Guidance for Claude Code when working with the Kanboard service on the Agap server.

## Overview

Kanboard is the kanban board for Agap. Tasks can be **assigned to the `claude` bot user**, and Claude acts on them via the `mcp__agap__kanboard_*` MCP tools (server `agap`). This directory holds only the Docker Compose config; the board data lives in a Docker volume.

- Container `kanboard`, image `kanboard/kanboard:latest`, port `127.0.0.1:4800:80`
- Storage: SQLite in the `data` volume (`/var/www/app/data/db.sqlite`)
- JSON-RPC API at `/jsonrpc.php`; app-wide admin auth = HTTP Basic `jsonrpc:<token>`
- App token stored in Vaultwarden as `KANBOARD_TOKEN`

### The `claude` bot user

- User `claude` = id **2**, role `app-admin`, web password in Vaultwarden `KANBOARD_CLAUDE_PASSWORD`
- **Gotcha:** `app-admin` only grants *visibility*. To be **assignable** as a task owner, a user must be a **project member**. `claude` is added as `project-member` to every project. Any *new* project needs this too, or assigning/creating tasks owned by `claude` returns `false`. Add via JSON-RPC `addProjectUser(project_id, 2, "project-member")`.

## Finding tasks assigned to Claude

**Primary method — use the dedicated MCP tool.** It lists tasks owned by the `claude` bot user across *all* projects in one call:

```
mcp__agap__kanboard_my_tasks(status="open")     # default: open tasks
mcp__agap__kanboard_my_tasks(status="all")      # open + closed
mcp__agap__kanboard_my_tasks(status="closed")
```

Returned tasks have `owner_id: 2` (claude) and include `project_id`, `project_name`, `column_id`, `title`, etc. Use `mcp__agap__kanboard_get_task(task_id=<id>)` for full detail (description, subtasks, comments).

**Per-project search** — Kanboard query syntax, scoped to one project:

```
mcp__agap__kanboard_search_tasks(project_id=<id>, query="assignee:claude status:open")
```

Useful query filters: `assignee:claude`, `status:open`, `due:today`, `color:red`.

## Working a task

Typical flow once a task is found:

1. `kanboard_get_task(task_id)` — read full detail
2. `kanboard_change_task_status` / `kanboard_move_task` — mark in-progress / move column
3. `kanboard_add_comment` — record progress or findings
4. `kanboard_change_task_status` — close when done

Discover the board layout with `kanboard_list_projects` and `kanboard_get_project(project_id)` (returns columns + swimlanes, needed to move cards).

## Full MCP toolset (`mcp__agap__kanboard_*`)

`list_projects`, `get_project`, `list_users`, `list_tasks`, `my_tasks`, `get_task`,
`search_tasks`, `project_activity`, `create_task`, `update_task`, `move_task`,
`assign_task`, `change_task_status`, `add_comment`, `remove_comment`,
`create_subtask`, `update_subtask`, `remove_task`.

Writes are authored as `claude` (via `user_id`) using the app-wide `KANBOARD_TOKEN`.

## Common Commands

```bash
docker compose up -d       # start
docker compose restart     # restart
docker compose logs -f     # logs

# Read the API token from the DB (matches Vaultwarden KANBOARD_TOKEN)
docker exec kanboard php -r '$db=new PDO("sqlite:/var/www/app/data/db.sqlite"); echo $db->query("SELECT value FROM settings WHERE option=\"api_token\"")->fetch()[0];'
```

## MCP server

The `kanboard_*` tools are implemented in `agap-mcp` (`/home/alvis/agap_git/agap-mcp`, `src/kanboard.js`, port 3100, tool name `agap`). Env: `KANBOARD_URL`, `KANBOARD_TOKEN`, `KANBOARD_BOT_USER=claude`. After editing the server:

```bash
cd /home/alvis/agap_git/agap-mcp && docker compose build && docker compose up -d
```

New/changed tools appear after Claude reconnects to the MCP.

## Gitea wiki

Kanboard is documented on the AgapHost wiki `Kanboard` page (`http://localhost:3000/alvis/AgapHost/wiki`). Update it when the setup changes — see the parent `../CLAUDE.md` for wiki edit instructions.