The Kanban board

Kanban is SenClaw's built-in work board (the Kanban item in the sidebar, in both the desktop app and the Web UI) with one twist over an ordinary board: agents pick up and run the cards in the Ready column when you switch the dispatcher on. You arrange the work — the AI does it — the results come back to the board.

The data lives in its own SQLite file ~/.senclaw/space-apps/kanban/kanban.db, separate from the daemon's main DB.

Concepts

Board → columns → cards. A board can be given a Workspace folder — the agent's working directory; output files land there.

Six default columns (the "Hermes" workflow — the Standard template):

A card carries: a description, a priority (low/medium/high/urgent — decides pick-up order), an assignee (a worker persona name — creates worker lanes), labels, a tenant, dependencies (an unfinished parent locks the child 🔒 — it will not be picked up), subtasks (progress shown as x/y), and a comment thread — where the agent reports its results.

Creating a board

New board

New board → a Title, a Columns template, and optionally a Workspace folder (Browse…). Three templates ship built in:

AI board

AI board → enter a Goal (say "Plan a customer workshop in 6 weeks" — the board comes out in whatever language you write the goal in) → Generate:

• Leave "✨ AI generates columns" on → the AI designs the columns and 8–16 cards (mostly in Todo/Triage; the in-flight columns start empty).
• Pick a template instead → the columns come from the template and the AI only writes cards, into Todo.

This calls SenClaw's active LLM (configure a model first — Settings → LLM). It runs synchronously: the dialog waits until it finishes, then opens the board; a failure shows "AI failed: …".

AI Task (desktop only, inside an open board)

AI Task takes one request and breaks it into tasks on the current board. ⚠️ It currently runs the "AI generates columns + cards" branch — new columns are appended to the end of the board; repeated use multiplies columns.

Agents running cards — the Ready column

The switch

Settings → Autonomous tasks → "Auto-run Kanban tasks (dispatcher)" — default OFF ("Agents act unattended — leave OFF unless you want that"). Flipping it takes effect at the next tick and applies to every board at once (a board without the Ready + In Progress pair is skipped).

The cycle (every 30 seconds)

1. Todo → Ready: Todo cards with no open dependencies are promoted to the end of Ready. Triage never moves — park work there to keep it human-gated.
2. Pick-up: Ready cards with no open dependencies, in priority order urgent > high > medium > the rest, then by position in the column. Default limits: 3 workers system-wide, 1 job per assignee (unassigned cards only count against the global cap).
3. Run: the card moves to In Progress; the agent's prompt is the card's title + description; it works inside the board's Workspace folder (or a per-card scratch directory when the board has none); a card with an assignee runs as that persona. The agent is told to read the card's detail first and must close out with kanban_complete or kanban_block; code changes must be blocked with a review-required: … reason so a human reviews them.

How a run ends

Results live in the card's comment thread (open the card to read them); produced files land in the Workspace folder. There is no OS notification when a card finishes — follow the Activity drawer (⚡): Running now plus the Recent worker feed (the last 30 lines).

There is no cancel button for a running card. Switching the toggle off only stops the next tick; the current run continues until it finishes or hits the 10-minute cap. To pre-empt one, drag the card out of Ready before it is picked up.

Tuning (environment variables)

SENCLAW_DISPATCH_ENABLED (default false) · SENCLAW_DISPATCH_INTERVAL_SECS (30, floor 5) · SENCLAW_DISPATCH_MAX_CONCURRENT (3) · SENCLAW_DISPATCH_PER_ASSIGNEE (1) · SENCLAW_DISPATCH_MAX_TURNS (40) · SENCLAW_DISPATCH_TIMEOUT_SECS (600).

Working the board

• Drag cards between columns. Into Done = complete; out again = reopened.
• Add card at the foot of every column (type a title, Enter). Add column asks for a Title + Type (role). Deleting a column: the ⋯ menu on the column — ⚠️ the desktop app asks no confirmation and deletes the cards inside it. Deleting a board: the trash icon on the board list (confirmed; wipes everything, no undo).
• Click a card for the detail view: Complete (asks for a summary) / Block (asks for a reason) / Unblock; change the Column, Priority, Assignee (a worker profile picked from the persona list) and Labels; Break down (AI) — the AI splits the card into 4–8 subtasks in the same column; Comments (your notes are saved under the name "Bạn" — You); and the Dependencies list (read-only in the UI — add and remove over MCP/REST).
• Worker lanes: group cards by assignee inside each column — on by default on desktop, a toggle on the web. With a worker filter dropdown.
• WIP limits (the Advanced template) only warn in red when exceeded — they never block a drop.
• UI differences: Rename board is web-only (the pencil icon); AI Task is desktop-only. due_date exists in the data and API but has no UI yet.

The board updates in realtime over WebSocket (the daemon broadcasts kanban:update; worst-case delay about 2 seconds).

Column templates (Plugins → Kanban)

The Plugins → Kanban page manages the reusable column templates offered when creating a board:

• New template builds a custom one; Import accepts pasted JSON; every template has Export (copy as JSON) for sharing.
• The built-ins (Standard/Advanced/Simple) cannot be edited or deleted — use Duplicate as custom and edit the copy.

Using Kanban from chat — MCP tools

The MCP server: **senclaw-kanban** (stdio, command senclaw kanban-server); full tool names have the shape mcp__senclaw-kanban__<tool>.

⚠️ This server is not part of the default MCP set of chat agents — it is granted automatically only to dispatcher workers. For a chat agent to touch boards, register an extra MCP server pointing at senclaw kanban-server (or use the REST API).

REST API (quick reference)

Mounted at /api/kanban/* on the daemon (UI port 18788):

GET  /api/kanban/boards            POST /api/kanban/boards            # list / create {title, template_id?, workspace_dir?}
GET  /api/kanban/board?id=         POST /api/kanban/board/rename|delete
GET  /api/kanban/templates         POST /api/kanban/templates(/delete)
POST /api/kanban/column/add|update|delete|reorder
GET  /api/kanban/card?id=          POST /api/kanban/card/add|update|move|delete
POST /api/kanban/card/complete|block|unblock|comment
POST /api/kanban/link/add|remove
POST /api/kanban/generate          # AI board {goal, template_id?, board_id?}
POST /api/kanban/breakdown         # AI subtasks {card_id}
GET  /api/kanban/activity?board_id=  # {running[], recent[]}
GET  /api/kanban/assignees?board_id=
GET/POST /api/dispatch-config      # {enabled} — the dispatcher switch

(There is also a /api/kanban/chat* group — a per-board AI chat backend that exists but no UI consumes yet.)

Gotchas

1. Want agents to run the board? Use Standard or Advanced. Simple has no Ready column, so the dispatcher skips it.
2. The dispatcher is a global switch — on means every eligible board; there is no per-board toggle.
3. Todo drains into Ready while the dispatcher is on — park not-yet-ready work in Triage.
4. A failed card sits in Blocked until you Unblock it (read the gave_up: comment first). A dead worker's card returns to Ready after 15 minutes and gets picked up again — a task that always fails can loop; fix its description, or drag it to Triage to stop it.
5. Deleting a column on desktop has no confirmation and takes every card inside it.
6. AI Task (desktop) appends new columns to the current board — repeated use duplicates columns.
7. WIP limits warn, never block. Dependency-cycle detection only blocks the direct A↔B pair, not longer loops.
8. AI board and Break down need a configured LLM; a model returning broken JSON shows "AI failed: could not parse board JSON…".

In the SenClaw repo

The engine is src/kanban/ — db.rs (DB and workflow), api.rs (REST), dispatch.rs plus src/agent/mcp_dispatch/ (the dispatcher), llm.rs (AI board and breakdown), mcp.rs (the MCP server) and templates.rs. The desktop UI is desktop_app/lib/features/kanban/, the web UI web/src/pages/KanbanPage.tsx, and the dispatcher knobs live in src/config.rs (SENCLAW_DISPATCH_*).