Examples & Recipes

Concrete workflows to copy, adapt, and ship. Each example is self-contained and builds on standard CLI, API, or SDK operations.

Workflow recipes

Personal dev workflow

A board that lives inside your project repo. Add cards from the terminal; review the board in VS Code without leaving your editor.

kl init
kl add --title "Refactor auth module" --priority high
kl add --title "Write tests" --label testing
kl serve   # open at localhost:3000

Team sprint board

Shared board committed to the monorepo. Every card change is a commit. Sprint reviews happen in pull requests.

kl boards add --id sprint-q2 --name "Q2 Sprint"
kl add --title "User profile page" \
  --board sprint-q2 \
  --assignee alice --priority high \
  --meta sprint=Q2 --meta points=5

Bug tracker with Slack webhook

Dedicated board for bug reports with triage labels and a Slack webhook on card creation.

kl boards add --id bugs --name "Bug Tracker"
kl webhooks add \
  --url https://hooks.slack.com/services/... \
  --events task.created,task.moved
kl add --title "Login fails on Safari" \
  --board bugs --priority critical \
  --label "bug,auth"

AI agent backlog (MCP)

Let Claude or Codex read your backlog, pick the next task, and move cards through the workflow.

kl mcp

# Add to Claude MCP config:
# { "command": "kl", "args": ["mcp"] }

# Claude can now list, create,
# move, and log cards directly.

CI/CD pipeline tracking

Attach named actions to deployment cards. CI fires the action via the REST API and logs the build result.

kl add --title "Release v2.1.0" \
  --actions "deploy,rollback,notify"

curl -X POST http://localhost:3000/api/\
boards/default/cards/release-v2-1-0/\
actions/deploy

SQLite for concurrent writes

Swap markdown file storage for SQLite when multiple CI jobs or team members write at the same time.

kl storage migrate-to-sqlite
kl storage status   # confirm provider

# Migrate back any time:
kl storage migrate-to-markdown

Technical reference examples

The patterns below show the same operations across CLI, REST API, and SDK interfaces.

Create and triage cards

CLI

# Create a high-priority bug
kl add --title "Login timeout on mobile" --priority high --label "bug,mobile"

# Assign and move to In Progress
kl edit login-timeout-on-mobile --assignee alice
kl move login-timeout-on-mobile in-progress

# List all high-priority open cards
kl list --priority high --status todo

REST API

curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"content": "# Login timeout on mobile", "priority": "high", "labels": ["bug","mobile"]}'

SDK

const card = await sdk.createCard({
  title: 'Login timeout on mobile',
  priority: 'high',
  labels: ['bug', 'mobile'],
});
await sdk.moveCard(card.id, 'in-progress');

Search with filters

CLI — fuzzy + metadata tokens

# Exact search for "release" in the backend team
kl list --search "release meta.team: backend"

# Fuzzy search tolerates typos
kl list --search "meta.team: backnd api plumbng" --fuzzy

# Combine free text with structured metadata filters
kl list --search "release" --fuzzy --meta sprint=Q1 --meta links.jira=PROJ-123

REST API

curl "http://localhost:3000/api/tasks?q=release&fuzzy=true&meta.team=backend"

Register a webhook

CLI

kl webhooks add \
  --url https://example.com/hook \
  --events task.created,task.moved \
  --secret mysecret

REST API

curl -X POST http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hook", "events": ["task.created","task.moved"], "secret": "mysecret"}'

SDK

await sdk.createWebhook({
  url: 'https://example.com/hook',
  events: ['task.created', 'task.moved'],
  secret: 'mysecret',
});

Attach and submit a form

Define a reusable incident-report form in .kanban.json, attach it to a card, then submit data through any interface.

Define in .kanban.json

{
  "forms": {
    "incident-report": {
      "schema": {
        "type": "object",
        "properties": {
          "severity": { "type": "string", "enum": ["low","medium","high","critical"] },
          "owner": { "type": "string" }
        },
        "required": ["severity","owner"]
      }
    }
  }
}

Attach and submit via CLI

kl add --title "Investigate outage" --forms '[{"name":"incident-report"}]'
kl form submit investigate-outage incident-report \
  --data '{"severity":"high","owner":"alice"}'

Submit via REST API

curl -X POST http://localhost:3000/api/tasks/investigate-outage/forms/incident-report/submit \
  -H "Content-Type: application/json" \
  -d '{"data": {"severity": "high", "owner": "alice"}}'

Multi-board workflow

CLI

# Create separate boards
kl boards add --id bugs --name "Bug Tracker"
kl boards add --id roadmap --name "Road Map"

# Work with a specific board
kl add --title "Fix login timeout" --board bugs
kl list --board roadmap --status todo

# Transfer a card between boards
kl transfer fix-login-timeout --from bugs --to roadmap

AI agent integration (MCP)

Claude Code setup

{
  "mcpServers": {
    "kanban": {
      "type": "stdio",
      "command": "npx",
      "args": ["kanban-lite", "mcp"],
      "env": { "KANBAN_DIR": "/path/to/.kanban" }
    }
  }
}

Example agent instructions

# Claude can now run things like:
list_cards status=todo priority=high
create_card title="Research auth options" status=backlog
move_card card_id=research-auth-options status=in-progress

Agent orchestration examples

Step-by-step build guides for running kanban-lite inside popular AI agent frameworks. Each example is a self-contained runnable app with a matching guide under /docs/examples/ and source under examples/.

Chat SDK / Vercel AI

A kanban-lite-backed triage assistant built with the Vercel AI ecosystem — streaming chat interface, board-native task creation, and a Next.js app shell.

examples/chat-sdk-vercel-ai/

View guide →

LangGraph Python

Durable backlog orchestration with human-approval interrupts. Each graph step maps to a kanban-lite card progressing through an approval checkpoint.

examples/langgraph-python/

View guide →

Mastra Agent Ops

Supervisor-style project-ops orchestration: a Mastra agent network with approval-aware steps that read and write kanban-lite tasks.

examples/mastra-agent-ops/

View guide →

Related: CLI Reference · REST API · SDK · MCP Server · Forms · Webhooks

Read the FAQ →