Kanban for team of AI agents
A team of AI agents needs a board that a human runs and the agents can’t get around. That board is now its own open-source repo: busyyaks_agents_kanban_module, Ruby module AgentsKanban, Apache-2.0.
It is the board inside busyyaks, split out so any app can embed it. It is a library with ports, not an app: no server, route, daemon or deploy. Your app supplies the transport, auth, identity and tmux delivery; the engine supplies the board, the rules and the agents’ MCP tools.
| Tests | 657 passing · 98.78% line coverage (Ruby on SQLite and Postgres, React on vitest) |
| Code | Ruby lib/ 7,776 lines · React src/ 13,179 lines · tests 7,074 lines |
| MCP | 33 kanban_* tools + the instruction text, worded from your config |
| Schema | v11, migrated by your app, tables under your prefix |
| Stack | Ruby 3.4 · Sequel · SQLite or PostgreSQL · React 18 + TypeScript |
Counts at the public main of 2026-11-14.
Hosts today
| Host | Stack | Board |
|---|---|---|
| busyyaks (reference) | Hanami 2.3 + SQLite | one coding board per repo: Backlog → To do → In progress → QA → Human Check → Ready to merge → Merged |
| a content app | Rails + Postgres | Waiting → Queued → Running → Done; a translation card waits for its article card |
Same engine, two very different workflows. Neither one is written anywhere in the engine’s code.
How it sits inside a host
Two entry points, and identity comes from which one a call uses: Api is the operator and Tools is the agents. The engine never infers a role from a name, so an agent cannot reach an operator-only move by calling itself the operator.
The board is data
A project’s columns, their order and the named transitions between them are rows in three tables (boards, board_columns, board_transitions). The operator edits them in a graph editor; agents read them with kanban_workflow. No column key or label appears in the engine’s code. The column’s type sets its rules:
| Type | Example columns | Rule |
|---|---|---|
parked | Backlog, Waiting | nobody listens; agents may create cards here |
queued | To do, Queued | one per board; a released card returns here; a worker can be spawned per card |
working | In progress, Author response | listened; the first one is where the watchdog releases from |
review | QA, Agent review | a further work column; review rounds are counted per loop column |
gate | Human Check, Ready to merge, Awaiting merge | waits for the operator; agents enter only through kanban_handoff; the operator’s one forward exit is the approval |
done | Merged, Done | exactly one per board; finishes a parent card; agents enter only from an approved gate |
cancelled | Cancelled | only the operator moves a card in or out |
A transition is {name, from, to, by} with by = operator, agent or any. Every move, whether from the web, MCP, a handoff, an ask or an approval, needs an edge for its actor, so move(transition: "Start work") either finds one or is refused with the transitions that exist. Saving a board is refused when it would drop a column that still holds cards, when it has no done column or more than one, and when it has more than 200 transitions.
Flags, not columns
A question for the operator used to be a column, so an agent’s card left its place in the review loop to ask. Now it’s a flag:
needs_operator: set bykanban_ask, or by a permission dialog seen on the owner’s screen. The operator’s comment clears it.blocked_external:kanban_block(reason, url)for CI, another card or a third party. It is not counted as waiting for the operator.
A flagged card keeps its column and refuses agent moves. After flags.reminder_hours it gets one reminder.
Gates an agent can’t skip
- Handoff:
kanban_handoffis the only way into a gate. The host sets what it requires:qawith at leastqa_min_charscharacters, the PR URL, the CI URL, and screenshots attached whenui_changeis true. - Approval: there is no approve tool for agents. With
requires_green_ci, the operator’s Approve is refused until the CI port reportssuccessfor that step’s PR. - Review loop: entering a loop column counts a round. At
max_roundsthe reviewer hands off with a summary of the counts, and the card is labelledunresolvedonly when threads are still open or need a human.
Rules that came from real failures
Each session rule closes a failure seen on the first host (SPEC § 8):
| What went wrong | The rule now |
|---|---|
| after a reboot the next session listened to nothing until someone claimed by hand | a launch registers the session first and adopts the project’s ownerless cards |
| an agent created a card and never claimed it | an agent’s kanban_create is owned by its session from the insert, or refused |
| an agent asked in plain chat; nobody saw it | kanban_ask claims and asks in one call; the MCP instructions say never to ask only in chat |
| yesterday’s dialog question was still on the card | dialogs no longer on screen expire before every delivery |
| three uncoordinated sessions on one project | max_sessions, max, max_per_project refuse the launch, naming who runs |
| the agent had the wrong column in mind | every card JSON carries column_label; the prompt names each adopted card’s column |
The MCP tools
| Group | Tools |
|---|---|
| read | kanban_board, kanban_card, kanban_workflow, kanban_labels, kanban_attachments, kanban_attachment_get |
| own | kanban_register, kanban_claim, kanban_create, kanban_session_board |
| work | kanban_move, kanban_update, kanban_comment (+ edit, delete), kanban_pr_assign, kanban_due_set, kanban_attach |
| ask and block | kanban_ask, kanban_block, kanban_unblock |
| hand over | kanban_handoff |
| checklists, labels | 8 checklist tools, kanban_label_save, kanban_label_delete, kanban_labels_set |
tools.instructions is the MCP server’s instruction text, worded from the host’s config, so every host tells its agents the same rules: claim before work, ask on the card, hand off with kanban_handoff, never poll.
Ingest it
There is no gem or npm package, on purpose: you read one sha in the open and vendor it.
- Copy
ruby/,react/src/andfixtures/at a sha. Your script pins it in aVENDOR.mdand refuses to overwrite a copy that has drifted from its pin. - Configure: copy
config.example.yml(every key documented, every key required) to e.g.config/kanban.yml. - Migrate and seed: a migration calls
Schema.migrate!pinned to its step, thenBoardRepo#seed!withboard.example.yml. - Wire: route your operator API to
Api, serveToolsfrom your MCP endpoint, runNotifier#deliver/#watchin a loop. - Mount:
<Board>and<LaunchBar>over your ownKanbanApi/LaunchApiadapters.
config = AgentsKanban::HostConfig.load("config/kanban.yml")
AgentsKanban::Schema.migrate!(db, prefix: config.table_prefix, to: 11)
store = AgentsKanban::Store.new(db, config: config, markdown: md, boards: ->(slug) { projects.exist?(slug) })
api = AgentsKanban::Api.new(store: store, attachments: files, markdown: md, projects: lookup,
press: press, sessions: -> { live_tmux_names }, launcher: my_launcher, grace: 60)
tools = AgentsKanban::Tools.new(store: store, attachments: files, projects: lookup,
sessions: -> { live_tmux_names }, card_url: ->(slug, id) { "https://board.example/…" })
status, body = api.move(id, { "transition" => "Start work" }, by: current_user)
tools.call("kanban_claim", args) # a JSON string; a refusal raises Invalid / Denied with the reason
Design rules
- No fallbacks. A missing key, an unknown column or a session that can’t be verified raises an error with the reason. Nothing is replaced with a default column or a guess.
- A host is config, not a branch. Launchers, agent types, caps, gates and the theme live in
HostConfig. A new CLI family is a new launcherkind, not anif. - The engine starts nothing. It hands your launcher the argv and the prompt and records the session; tmux and processes stay yours.
- Agents never approve. Gates are entered by handoff and left by the operator.
Not for
- A hosted service. It ships no server. You need an app to embed it in, a Ruby one with Sequel.
- Teams of humans with roles. There is one operator and there are agents.
- Using it without code. For a ready-made dashboard, run busyyaks, which wraps it.
FAQ
What is agents_kanban?
An open-source (Apache-2.0) kanban engine in Ruby and React for a team of AI agents and one human operator. Agents work cards through 33 kanban_* MCP tools; the operator approves in gates the agents cannot pass.
How is it different from busyyaks?
busyyaks is a full self-hosted dashboard: Docker services, a launcher, a scanner, reports. agents_kanban is the board inside it, as a library any Ruby + React app can vendor.
Which databases does it support?
SQLite and PostgreSQL through Sequel. The test suite runs on both.
Does it only work with Claude Code?
A launcher’s kind is claude_code or hermes; each kind is one class that builds that CLI’s argv. Delivering a ping depends on the host’s tmux client.
Related
- busyyaks: self-hosted kanban for Claude Code: the reference host.
- How I reached 100 quality PRs a day with an agents kanban: the process the board runs.
- How I manage teams of coding agents on a private project locally: where it started.
Code, SPEC and issues: github.com/robertziel/busyyaks_agents_kanban_module.