Local-first kanban for AI-agent workflows. SQLite, FastAPI, no auth, no cloud.
A self-hosted kanban board designed to be driven by AI coding agents (Claude Code, Cline, opencode, Open WebUI, any function-calling LLM). Drag-drop in browser, REST + MCP for agents. Multi-project, light/dark theme, markdown plan-file import, automation rules.
More themes & profiles
| Dark theme | Cyberpunk profile | Horizon profile |
|---|---|---|
 |
 |
 |
Toggle theme with t, cycle profiles with p. Or pin a theme/profile via URL: ?theme=light&profile=cyberpunk.
- 9 workflow columns: Backlog → Approved → Analyst → In progress → Testing → UAT → Done, plus Blocked / Cancelled.
- Multiple projects in one DB, URL-routed (
/p/{slug}), each with optional Claude Code-project directory binding. - Light/dark theme switcher (
t), density toggle (d), collapsible columns, sidebar. - Search + filter chips, keyboard shortcuts (
/,n,r,\,Esc). - Inbox watcher: drop a
.mdintokanban_data/inbox/, get a card in 5 sec. PointKANBAN_INBOX_DIRat any folder you like — even~/.claude/projects/<proj>/memory/inbox/for Claude session captures. - PLAN.md import (loose-mode parser): any
## Section→ cards in backlog with section-name in description. - Automation rules (
kanban_data/rules.json):task_idle: status=done, days=14 → move_to cancelled, etc. Hot-reloaded. - Outbound webhooks (
kanban_data/webhooks.json): POST to Slack / Telegram / any HTTP endpoint ontask_created/task_moved/task_commented/task_updated. 3 formats:generic,slack,telegram. - MCP server (
kanban_mcp/) with 14 tools for Claude Code / Cline (project-aware:kanban_projects,kanban_board,kanban_search,kanban_my_active). - REST API + auto-generated OpenAPI for opencode / Open WebUI / any LLM with function calling.
5 minutes from clone to an AI agent doing your work for you: see QUICKSTART.md.
Bare minimum (one command after install):
# Install uv once: `curl -LsSf https://astral.sh/uv/install.sh | sh` or `brew install uv`
git clone https://github.com/<your-user>/agent-kanban.git
cd agent-kanban
uv run python -m kanban_ui # http://localhost:7777uv run auto-creates a .venv/, installs deps from pyproject.toml (~5 sec on a warm cache), and launches the server.
Legacy pip / venv path
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m kanban_ui # http://localhost:7777requirements.txt is kept in sync with pyproject.toml for Dependabot and pip-only environments.
Optional — auto-start on login (macOS):
bash scripts/install_launchd.sh install # macOS launchd
bash scripts/install_launchd.sh status
bash scripts/install_launchd.sh uninstallLogs: ~/Library/Logs/agent-kanban/{stdout,stderr}.log.
Pick the integration matching your agent:
| Agent | Transport | Reference |
|---|---|---|
| Claude Code (Anthropic CLI) | MCP stdio via ~/.claude.json or .mcp.json |
docs/INTEGRATION.md#claude-code |
| Cline (VSCode extension, legacy stdio) | MCP stdio, same config block | docs/INTEGRATION.md#cline |
| 🆕 Cursor | HTTP MCP @ http://localhost:7777/mcp |
docs/INTEGRATION.md#cursor |
| 🆕 Cline (new versions) | HTTP MCP @ http://localhost:7777/mcp |
docs/INTEGRATION.md#cline-http |
| opencode (sst/opencode) | OpenAPI tools / REST | docs/INTEGRATION.md#opencode |
| Open WebUI | OpenAPI Tool Server pointing at /openapi.json |
docs/INTEGRATION.md#open-webui |
| Generic LLM (Hermes / Llama / Ollama / Mistral / vLLM) | function-calling + REST | docs/INTEGRATION.md#generic-llm |
| MCP Inspector (debugging) | HTTP MCP @ http://localhost:7777/mcp |
docs/INTEGRATION.md#mcp-inspector |
The kanban runs two MCP transports in parallel: legacy stdio (python -m kanban_mcp, for Claude Code) and streamable HTTP at /mcp (for Cursor / new Cline / Open WebUI / MCP Inspector / anything that speaks the MCP SSE transport).
Static OpenAPI schema: docs/openapi.yaml. Interactive Swagger: http://localhost:7777/docs.
Real-world flows: docs/USECASES.md — 11 use cases (solo dev, team Slack, legacy import, multi-project, agent session, auto-launch, etc.).
- vs. Trello/Jira/Linear — local-first; no SaaS account, no rate limits, your data on your disk.
- vs. plain TODO.md — drag-drop, history, multi-project, MCP integration, automation rules.
- vs. building your own — already battle-tested for solo + agent workflow.
| Variable | Default | Purpose |
|---|---|---|
KANBAN_HOST |
127.0.0.1 |
bind address |
KANBAN_PORT |
7777 |
port |
KANBAN_DB |
<repo>/tasks.db |
SQLite path |
KANBAN_ACTOR |
user |
author name written to history |
KANBAN_DEFAULT_PROJECT_ID |
default |
id of seed project on first launch |
KANBAN_DEFAULT_PROJECT_NAME |
Default |
display name of seed project |
KANBAN_DEFAULT_PROJECT_COLOR |
#F10D30 |
accent color of seed project |
KANBAN_INBOX_DIR |
<repo>/kanban_data/inbox |
inbox watcher folder |
KANBAN_RULES_FILE |
<repo>/kanban_data/rules.json |
automation rules |
KANBAN_WEBHOOKS_FILE |
<repo>/kanban_data/webhooks.json |
outbound webhook notifications |
KANBAN_AUTOMATION_INTERVAL |
60 |
rule engine interval (sec) |
KANBAN_INBOX_INTERVAL |
5 |
inbox poll interval (sec) |
KANBAN_CORS_ORIGINS |
(empty) | comma-separated origins for CORS (e.g. for remote Open WebUI) |
KANBAN_PROJECT_ID |
(empty) | for MCP server: default project_id when agent calls kanban_create without one |
agent-kanban/
├── kanban_store/ SQLite store + schema (4 tables, 4 migrations)
├── kanban_ui/ FastAPI web UI + automation/{inbox,rules,plan_md}
│ └── static/ index.html · styles.css · app.js · vendor/Sortable
├── kanban_mcp/ MCP server (14 tools)
├── seed/ generic example tasks
├── examples/ llm-tool-calling demo scripts
├── docs/ INTEGRATION.md, openapi.yaml, screenshots
├── tests/ pytest tests
├── scripts/ install_launchd.sh
├── snapshots/ JSON snapshots (gitignored except .gitkeep)
└── kanban_data/ runtime DB, inbox/, rules.json (gitignored)
- Bidirectional sync: edits in UI write back to PLAN.md.
- GitHub Issues importer (already has source-config table; needs gh API client).
- Multi-user mode with simple cookie-based auth.
- Optional Postgres backend.