Agent Kanban

English · Русский

An AI-native kanban board where agents (Codex, Hermes, etc.) pull tasks via the Model Context Protocol. The board is passive — it never spawns or controls agents. You point your agents at the board via MCP config, and they self-serve tasks through get_next_task / claim_task.

Why?

Most agent orchestrators push work: a dispatcher decides who does what and sends it. Agent Kanban inverts this — the board is a passive MCP server. Agents discover and claim work when they're ready, exactly like a developer picks a ticket from a real kanban. This decouples "what needs doing" (the board) from "who does it and when" (the agent), and works with any agent that speaks MCP — no glue code per agent.

Features

• Pull-based MCP — board exposes 11 tools (get_next_task, claim_task, post_progress, request_review, …) over the streamable-HTTP transport
• Hard assignment — reserve a task for a specific agent; others don't see it
• Live progress feed — agents stream diffs, text, artifacts, errors; you comment back and the agent reads your feedback on the next turn
• Bilingual UI — Russian / English, with a one-click language toggle
• Review diffs — the board collects git diff base...branch on request_review and renders it inline (Shiki syntax highlighting)
• Design system — dark-first, single-amber-accent UI built on tokens
• Self-hosted — FastAPI + PostgreSQL + React; ships as a Docker image

Screenshots

<table> <tr> <td width="50%" align="center"><b>Board (dark)</b></td> <td width="50%" align="center"><b>Card detail</b></td> </tr> <tr> <td><img src="docs/screenshots/board.png" alt="Board view"></td> <td><img src="docs/screenshots/card-detail.png" alt="Card detail"></td> </tr> <tr> <td align="center" colspan="2"><b>First-run setup</b></td> </tr> <tr> <td align="center" colspan="2"><img src="docs/screenshots/login.png" alt="Login / setup screen" width="50%"></td> </tr> </table>

Architecture

See docs/superpowers/specs/2026-07-05-agent-kanban-design.md for the full design. Phase 1 MVP scope is documented in docs/superpowers/plans/2026-07-06-agent-kanban-phase1-mvp.md.

Quickstart (local dev)

Prerequisites

• Python 3.11+
• uv (install: curl -LsSf https://astral.sh/uv/install.sh | sh)
• Node.js 20+ and pnpm
• PostgreSQL 16+ running locally

1. Database

createdb kanban  # or use docker: see docker-compose.yml
cp .env.example .env  # DATABASE_URL defaults to port 5436 (matches docker-compose ak-pg)
uv run kanban migrate

2. Backend

uv sync --extra dev
uv run kanban serve

3. Frontend (separate terminal)

cd web
pnpm install
pnpm dev   # http://localhost:5173, proxies to :7331

4. Point an agent at the board

Add to your agent's MCP config:

Codex (~/.codex/config.toml):

[mcp_servers.kanban]
url = "http://localhost:7331/mcp"

Hermes (~/.hermes/config.yaml):

mcp_servers:
  kanban:
    url: http://localhost:7331/mcp

Then instruct your agent: "Check the kanban board for tasks via get_next_task."

Agent workflow

1. Create a task in the UI. It starts in todo.
2. Drag it to the READY column. It's now available to agents via get_next_task.
3. Instruct your agent (e.g. Codex, Hermes) to check the board:
   • Call get_next_task to discover work.
   • Call claim_task to take it.
   • Call post_progress to report what it's doing.
   • Call request_review when ready for your review, or complete_task when done.
4. Watch progress events stream into the card detail view in real time.
5. Add comments to give the agent follow-up instructions; the agent reads them via get_comments.

Agents must pass their identifier as the agent argument to mutation tools (claim_task, post_progress, complete_task, request_review, post_comment, post_artifact, set_task_branch, set_task_pr). The board authorizes mutations by checking claimed_by == agent.

Coding tasks (git/PR)

For tasks that touch a git repo, set repo_path and base_branch when creating the task. The board does NOT create branches or PRs — your agent does that with its own git tools. The board records what the agent reports and renders a review diff.

Agent workflow for a coding task:

1. claim_task — receives repo_path and (if set) base_branch.
2. Create a branch in repo_path with the agent's git tool.
3. set_task_branch(task_id, agent, branch) — record it so the UI shows it and the diff can be collected.
4. Commit work on that branch.
5. request_review(task_id, agent, summary) — the board runs git -C <repo_path> diff <base>...<branch> once and stores the result as a diff event visible in the card's progress feed.
6. Open a PR with the agent's GitHub tool, then set_task_pr(task_id, agent, pr_url, "open").
7. When merged, set_task_pr(task_id, agent, pr_url, "merged") then complete_task.

If repo_path, base_branch (or the project's default_branch), or branch is missing, diff collection is skipped silently. If git diff fails, an error event is recorded instead, but the review request itself still succeeds.

Authentication

The board requires authentication. Two kinds of principals:

• Users (humans): log in with username + password via the web UI. Sessions are signed cookies.
• Tokens (agents): opaque bearer tokens, managed in the Admin panel. Each token is bound to an agent_name.

First run

On first startup with an empty database, the UI shows a setup screen: choose an admin username + password (8+ chars) and submit. Alternatively, set AGENT_KANBAN_BOOTSTRAP_ADMIN_PASSWORD to create the admin headlessly (for automation). After setup, log in and go to Admin → Tokens to mint tokens for your agents.

Pointing an agent at the board

Agents authenticate via a bearer token. In your agent's MCP config:

Codex (~/.codex/config.toml):

[mcp_servers.kanban]
url = "http://your-host:7331/mcp"
# Codex reads headers from config in newer versions; otherwise set the auth via env.
headers = { Authorization = "Bearer <your-token>" }

Hermes (~/.hermes/config.yaml):

mcp_servers:
  kanban:
    url: http://your-host:7331/mcp
    headers:
      Authorization: Bearer <your-token>

The token's agent_name MUST match the agent argument you pass to MCP tools. A token minted with agent_name=codex can call claim_task(agent="codex") but NOT claim_task(agent="hermes").

Production env vars

• SESSION_SECRET — signing key for session cookies. REQUIRED in production; set a long random string.
• PUBLIC_URL — the public base URL (e.g. https://kanban.example.com). Controls cookie Secure flag.
• AGENT_KANBAN_BOOTSTRAP_ADMIN_PASSWORD — first-run admin password (optional; if unset, the UI setup screen creates the first admin).

Docker

docker compose up -d

Runs the app on :7331 with Postgres in an internal-only container (not exposed to the host). The app connects to it over the compose network as postgres:5432. For local dev against a host-visible Postgres, see the standalone container note in "Database" above (port 5436).

Contributing

Contributions are welcome. The design spec and phased implementation plans live under docs/superpowers/ — they're a good map of the architecture and intent.

# clone, then:
uv sync --extra dev          # backend deps + test tooling
cd web && pnpm install       # frontend deps
uv run pytest -q             # 112+ tests
cd web && pnpm build         # type-check + bundle

Please open an issue first for non-trivial changes, so we can align on scope.

Credits

The UI is built on a design system inspired by Sergey Dmitriev's brand book — amber as the single UI accent, dark-first, with semantic-only status colors.

License

MIT © Sergey Dmitriev