{"id":49781435,"url":"https://github.com/nerkoman/agent-kanban","last_synced_at":"2026-05-11T21:01:08.920Z","repository":{"id":356712592,"uuid":"1233747789","full_name":"nerkoman/agent-kanban","owner":"nerkoman","description":"Local-first kanban for AI-agent workflows. Drag a task to Approved and your AI coding agent picks it up via MCP and drives it through analyst → in_progress → testing on its own. MCP for Claude Code \u0026 Cline, OpenAPI for opencode / Open WebUI / Ollama / any function-calling LLM. SQLite + FastAPI, runs on localhost.","archived":false,"fork":false,"pushed_at":"2026-05-09T12:13:27.000Z","size":633,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T12:29:22.087Z","etag":null,"topics":["agent","ai-agent","ai-tools","automation","claude-code","cline","fastapi","kanban","local-first","mcp","mcp-server","open-webui","openapi","opencode","project-management","python","self-hosted","sqlite","task-manager","webhook"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nerkoman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T10:00:18.000Z","updated_at":"2026-05-09T12:09:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nerkoman/agent-kanban","commit_stats":null,"previous_names":["nerkoman/agent-kanban"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/nerkoman/agent-kanban","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerkoman%2Fagent-kanban","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerkoman%2Fagent-kanban/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerkoman%2Fagent-kanban/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerkoman%2Fagent-kanban/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nerkoman","download_url":"https://codeload.github.com/nerkoman/agent-kanban/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerkoman%2Fagent-kanban/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32912661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"ssl_error","status_checked_at":"2026-05-11T17:08:45.420Z","response_time":120,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai-agent","ai-tools","automation","claude-code","cline","fastapi","kanban","local-first","mcp","mcp-server","open-webui","openapi","opencode","project-management","python","self-hosted","sqlite","task-manager","webhook"],"created_at":"2026-05-11T21:01:01.240Z","updated_at":"2026-05-11T21:01:08.905Z","avatar_url":"https://github.com/nerkoman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-kanban\n\n\u003e Local-first kanban for AI-agent workflows. SQLite, FastAPI, no auth, no cloud.\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)\n\nA self-hosted kanban board designed to be driven by AI coding agents\n(Claude Code, Cline, opencode, Open WebUI, any function-calling LLM).\nDrag-drop in browser, REST + MCP for agents. Multi-project, light/dark\ntheme, markdown plan-file import, automation rules.\n\n![Board — light theme](docs/screenshots/board-light.png)\n\n\u003cdetails\u003e\n\u003csummary\u003eMore themes \u0026 profiles\u003c/summary\u003e\n\n| Dark theme | Cyberpunk profile | Horizon profile |\n|---|---|---|\n| ![dark](docs/screenshots/board-dark.png) | ![cyberpunk](docs/screenshots/board-cyberpunk.png) | ![horizon](docs/screenshots/board-horizon.png) |\n\nToggle theme with `t`, cycle profiles with `p`. Or pin a theme/profile via URL: `?theme=light\u0026profile=cyberpunk`.\n\n\u003c/details\u003e\n\n## Features\n\n- 9 workflow columns: Backlog → Approved → Analyst → In progress → Testing → UAT → Done, plus Blocked / Cancelled.\n- Multiple projects in one DB, URL-routed (`/p/{slug}`), each with optional Claude Code-project directory binding.\n- Light/dark theme switcher (`t`), density toggle (`d`), collapsible columns, sidebar.\n- Search + filter chips, keyboard shortcuts (`/`, `n`, `r`, `\\`, `Esc`).\n- Inbox watcher: drop a `.md` into `kanban_data/inbox/`, get a card in 5 sec. Point `KANBAN_INBOX_DIR` at any folder you like — even `~/.claude/projects/\u003cproj\u003e/memory/inbox/` for Claude session captures.\n- PLAN.md import (loose-mode parser): any `## Section` → cards in backlog with section-name in description.\n- Automation rules (`kanban_data/rules.json`): `task_idle: status=done, days=14 → move_to cancelled`, etc. Hot-reloaded.\n- **Outbound webhooks** (`kanban_data/webhooks.json`): POST to Slack / Telegram / any HTTP endpoint on `task_created`/`task_moved`/`task_commented`/`task_updated`. 3 formats: `generic`, `slack`, `telegram`.\n- **MCP server** (`kanban_mcp/`) with 14 tools for Claude Code / Cline (project-aware: `kanban_projects`, `kanban_board`, `kanban_search`, `kanban_my_active`).\n- **REST API + auto-generated OpenAPI** for opencode / Open WebUI / any LLM with function calling.\n\n## Quickstart\n\n**5 minutes from clone to an AI agent doing your work for you:** see [QUICKSTART.md](QUICKSTART.md).\n\nBare minimum (one command after install):\n\n```bash\n# Install uv once: `curl -LsSf https://astral.sh/uv/install.sh | sh` or `brew install uv`\ngit clone https://github.com/\u003cyour-user\u003e/agent-kanban.git\ncd agent-kanban\nuv run python -m kanban_ui                     # http://localhost:7777\n```\n\n`uv run` auto-creates a `.venv/`, installs deps from `pyproject.toml` (~5 sec on a warm cache), and launches the server.\n\n\u003cdetails\u003e\n\u003csummary\u003eLegacy pip / venv path\u003c/summary\u003e\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/pip install -r requirements.txt\n.venv/bin/python -m kanban_ui                  # http://localhost:7777\n```\n\n`requirements.txt` is kept in sync with `pyproject.toml` for Dependabot and pip-only environments.\n\n\u003c/details\u003e\n\nOptional — auto-start on login (macOS):\n\n```bash\nbash scripts/install_launchd.sh install        # macOS launchd\nbash scripts/install_launchd.sh status\nbash scripts/install_launchd.sh uninstall\n```\n\nLogs: `~/Library/Logs/agent-kanban/{stdout,stderr}.log`.\n\n## AI agent integrations\n\nPick the integration matching your agent:\n\n| Agent | Transport | Reference |\n|---|---|---|\n| **Claude Code** (Anthropic CLI) | MCP stdio via `~/.claude.json` or `.mcp.json` | [docs/INTEGRATION.md#claude-code](docs/INTEGRATION.md#1-claude-code-mcp) |\n| **Cline** (VSCode extension, legacy stdio) | MCP stdio, same config block | [docs/INTEGRATION.md#cline](docs/INTEGRATION.md#2-cline-mcp) |\n| **🆕 Cursor** | HTTP MCP @ `http://localhost:7777/mcp` | [docs/INTEGRATION.md#cursor](docs/INTEGRATION.md#cursor-http-mcp) |\n| **🆕 Cline (new versions)** | HTTP MCP @ `http://localhost:7777/mcp` | [docs/INTEGRATION.md#cline-http](docs/INTEGRATION.md#cline-http-mcp) |\n| **opencode** (sst/opencode) | OpenAPI tools / REST | [docs/INTEGRATION.md#opencode](docs/INTEGRATION.md#3-opencode-rest--openapi) |\n| **Open WebUI** | OpenAPI Tool Server pointing at `/openapi.json` | [docs/INTEGRATION.md#open-webui](docs/INTEGRATION.md#4-open-webui-openapi-tool-server) |\n| **Generic LLM** (Hermes / Llama / Ollama / Mistral / vLLM) | function-calling + REST | [docs/INTEGRATION.md#generic-llm](docs/INTEGRATION.md#5-generic-function-calling-llm) |\n| **MCP Inspector** (debugging) | HTTP MCP @ `http://localhost:7777/mcp` | [docs/INTEGRATION.md#mcp-inspector](docs/INTEGRATION.md#mcp-inspector) |\n\nThe 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).\n\nStatic OpenAPI schema: [`docs/openapi.yaml`](docs/openapi.yaml). Interactive Swagger: `http://localhost:7777/docs`.\n\nReal-world flows: [`docs/USECASES.md`](docs/USECASES.md) — 11 use cases (solo dev, team Slack, legacy import, multi-project, agent session, auto-launch, etc.).\n\n## Why\n\n- **vs. Trello/Jira/Linear** — local-first; no SaaS account, no rate limits, your data on your disk.\n- **vs. plain TODO.md** — drag-drop, history, multi-project, MCP integration, automation rules.\n- **vs. building your own** — already battle-tested for solo + agent workflow.\n\n## Configuration (env vars)\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `KANBAN_HOST` | `127.0.0.1` | bind address |\n| `KANBAN_PORT` | `7777` | port |\n| `KANBAN_DB` | `\u003crepo\u003e/tasks.db` | SQLite path |\n| `KANBAN_ACTOR` | `user` | author name written to history |\n| `KANBAN_DEFAULT_PROJECT_ID` | `default` | id of seed project on first launch |\n| `KANBAN_DEFAULT_PROJECT_NAME` | `Default` | display name of seed project |\n| `KANBAN_DEFAULT_PROJECT_COLOR` | `#F10D30` | accent color of seed project |\n| `KANBAN_INBOX_DIR` | `\u003crepo\u003e/kanban_data/inbox` | inbox watcher folder |\n| `KANBAN_RULES_FILE` | `\u003crepo\u003e/kanban_data/rules.json` | automation rules |\n| `KANBAN_WEBHOOKS_FILE` | `\u003crepo\u003e/kanban_data/webhooks.json` | outbound webhook notifications |\n| `KANBAN_AUTOMATION_INTERVAL` | `60` | rule engine interval (sec) |\n| `KANBAN_INBOX_INTERVAL` | `5` | inbox poll interval (sec) |\n| `KANBAN_CORS_ORIGINS` | (empty) | comma-separated origins for CORS (e.g. for remote Open WebUI) |\n| `KANBAN_PROJECT_ID` | (empty) | for MCP server: default project_id when agent calls `kanban_create` without one |\n\n## Project layout\n\n```\nagent-kanban/\n├── kanban_store/    SQLite store + schema (4 tables, 4 migrations)\n├── kanban_ui/       FastAPI web UI + automation/{inbox,rules,plan_md}\n│   └── static/      index.html · styles.css · app.js · vendor/Sortable\n├── kanban_mcp/      MCP server (14 tools)\n├── seed/            generic example tasks\n├── examples/        llm-tool-calling demo scripts\n├── docs/            INTEGRATION.md, openapi.yaml, screenshots\n├── tests/           pytest tests\n├── scripts/         install_launchd.sh\n├── snapshots/       JSON snapshots (gitignored except .gitkeep)\n└── kanban_data/     runtime DB, inbox/, rules.json (gitignored)\n```\n\n## Roadmap\n\n- Bidirectional sync: edits in UI write back to PLAN.md.\n- GitHub Issues importer (already has source-config table; needs gh API client).\n- Multi-user mode with simple cookie-based auth.\n- Optional Postgres backend.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerkoman%2Fagent-kanban","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnerkoman%2Fagent-kanban","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerkoman%2Fagent-kanban/lists"}