--- title: KanBot emoji: πŸ€– colorFrom: gray colorTo: gray sdk: docker app_port: 7860 pinned: false license: apache-2.0 short_description: A Kanban board that IS the agent runtime. --- # KanBot **A Kanban board that IS the agent runtime.** Not a tracker agents update β€” a board where each card is a live agent task and the columns are execution states. Cards move themselves. Agents talk to each other through the card thread. You watch from a web view, poke it from the CLI, or nudge it from Telegram. The core inversion: **the board is the message bus and the state machine.** A card's column = its lifecycle state. Moving a card = a state transition = an event that fires an agent. The board isn't a dashboard β€” it's the scheduler. ``` backlog β†’ ready β†’ in-flight β†’ review β†’ done ↑ ↓ ↓ β†˜ └─────── ready β†β”€β”€β”€β”€β”€β”€β”˜ blocked every column change β†’ NOTIFY β†’ the Conductor dispatches an agent ``` ## Persistent storage `/data` is mounted from the `LoveLogicAI/kanbot-data` bucket as a persistent volume. The board's Postgres data and sandbox artifacts live there, so state survives restarts. ## Running The Dockerfile builds a Python 3.11 container with Postgres client tools. On boot it starts a local Postgres instance, applies `sql/001_schema.sql`, then launches the web server on port 7860. ```bash hf spaces restart LoveLogicAI/kanbot-backend ``` ## v0 scope The **headless heart**, running and testable tonight: | Piece | File | Role | |-------|------|------| | Frozen contract | `core/contract.py` | Columns, transition table, guards, card model β€” the single source of truth | | SQL schema | `sql/001_schema.sql` | `cards` + `board_events` + a `LISTEN/NOTIFY` trigger on every column change | | MCP server | `core/mcp_server.py` | The whole API β€” 9 tools. Enforces legal transitions + guards + idempotency | | Conductor | `core/conductor.py` | Subscribes to `kb_events`, dispatches the right agent per transition | | Workers | `core/workers.py` | Planner / executor / critic loops on the local M4 | | Reaper | `core/reaper.py` | Reclaims stale in-flight cards β†’ self-healing swarm | | CLI | `cli/kb.py` and `cli/kanbot_cli.py` | Board, claim, move, approve, and the JSONL agent protocol | | Web view | `web/server.py` + `web/index.html` | Live board over Postgres NOTIFYβ†’WebSocket. Single-file async server, no npm/build | ## Going live The checked-in default is dry-run. Executors propose tool calls and park in `blocked` until `kb approve`. Shell runs only after `KANBOT_DRY_RUN=0`, and then only inside `.sandbox/` with network off.