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.

Tests657 passing · 98.78% line coverage (Ruby on SQLite and Postgres, React on vitest)
CodeRuby lib/ 7,776 lines · React src/ 13,179 lines · tests 7,074 lines
MCP33 kanban_* tools + the instruction text, worded from your config
Schemav11, migrated by your app, tables under your prefix
StackRuby 3.4 · Sequel · SQLite or PostgreSQL · React 18 + TypeScript

Counts at the public main of 2026-11-14.

Hosts today

HostStackBoard
busyyaks (reference)Hanami 2.3 + SQLiteone coding board per repo: Backlog → To do → In progress → QA → Human Check → Ready to merge → Merged
a content appRails + PostgresWaiting → 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

How agents_kanban sits inside a host app: the operator's browser loads the React board, which calls the host's routes through a KanbanApi adapter into the engine's Api; Claude Code sessions in tmux call kanban_* tools on the host's MCP endpoint, which hands them to the engine's Tools; Api and Tools both go through Store, which applies the board's columns and workflow; Notifier delivers pings to the owning session through the host's tmux delivery port; Launch builds the argv and prompt the host's launcher port starts; the host injects the launcher, the HostConfig file, a Sequel database (SQLite or PostgreSQL) and the markdown, git, CI and clock ports. How agents_kanban sits inside a host a library with ports · no server, route or daemon of its own your host app routes · auth · MCP endpoint · ports agents_kanban · vendored at one pinned sha ports the host injects KanbanApi kanban_* ping argv Sequel Operatorbrowser Claude Code sessionsagents in tmux · one owns each card <Board>React 18 MCP endpointhost route tmux clientdelivery port Apithe operator Board · Workflowcolumns + transitions as rows Toolsthe agents Notifierpings · watchdog Launchargv + prompt Storecards · sessions · flags · gates · review rounds launcherstarts tmux HostConfigkanban.yml databaseSQLite · Postgres markdown · gitCI · clock · files operator sideagent siderules + data
What the engine does and what your app supplies. Pick a path, or hover a box or a wire (tap on a phone).
How agents_kanban sits inside a host app: the operator's browser loads the React board, which calls the engine's Api through the host's routes; Claude Code sessions call kanban_* tools on the host's MCP endpoint, which hands them to Tools; Api, Tools and Notifier all go through Store, which applies the Board and Workflow; Notifier pings the owning session through the host's tmux client; Launch builds the argv the host's launcher starts; the host injects the launcher, HostConfig, the database and the other ports. agents_kanban inside a host a library with ports · no server of its own agents_kanban one pinned sha your host app · the ports it injects Operatorbrowser Claude Code sessionsagents in tmux <Board>React 18 MCPhost route tmux clientdelivery Apioperator Toolsagents Notifierpings Store · cards · sessions · flags · gates Launch BoardWorkflow launcher config database md · git · CI operatoragentsrules + data
What the engine does and what your app supplies. Pick a path, or tap a box or a wire.

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:

TypeExample columnsRule
parkedBacklog, Waitingnobody listens; agents may create cards here
queuedTo do, Queuedone per board; a released card returns here; a worker can be spawned per card
workingIn progress, Author responselistened; the first one is where the watchdog releases from
reviewQA, Agent reviewa further work column; review rounds are counted per loop column
gateHuman Check, Ready to merge, Awaiting mergewaits for the operator; agents enter only through kanban_handoff; the operator’s one forward exit is the approval
doneMerged, Doneexactly one per board; finishes a parent card; agents enter only from an approved gate
cancelledCancelledonly 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:

A flagged card keeps its column and refuses agent moves. After flags.reminder_hours it gets one reminder.

Gates an agent can’t skip

Rules that came from real failures

Each session rule closes a failure seen on the first host (SPEC § 8):

What went wrongThe rule now
after a reboot the next session listened to nothing until someone claimed by handa launch registers the session first and adopts the project’s ownerless cards
an agent created a card and never claimed itan agent’s kanban_create is owned by its session from the insert, or refused
an agent asked in plain chat; nobody saw itkanban_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 carddialogs no longer on screen expire before every delivery
three uncoordinated sessions on one projectmax_sessions, max, max_per_project refuse the launch, naming who runs
the agent had the wrong column in mindevery card JSON carries column_label; the prompt names each adopted card’s column

The MCP tools

GroupTools
readkanban_board, kanban_card, kanban_workflow, kanban_labels, kanban_attachments, kanban_attachment_get
ownkanban_register, kanban_claim, kanban_create, kanban_session_board
workkanban_move, kanban_update, kanban_comment (+ edit, delete), kanban_pr_assign, kanban_due_set, kanban_attach
ask and blockkanban_ask, kanban_block, kanban_unblock
hand overkanban_handoff
checklists, labels8 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.

  1. Copy ruby/, react/src/ and fixtures/ at a sha. Your script pins it in a VENDOR.md and refuses to overwrite a copy that has drifted from its pin.
  2. Configure: copy config.example.yml (every key documented, every key required) to e.g. config/kanban.yml.
  3. Migrate and seed: a migration calls Schema.migrate! pinned to its step, then BoardRepo#seed! with board.example.yml.
  4. Wire: route your operator API to Api, serve Tools from your MCP endpoint, run Notifier#deliver / #watch in a loop.
  5. Mount: <Board> and <LaunchBar> over your own KanbanApi / LaunchApi adapters.
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

Not for

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.

Code, SPEC and issues: github.com/robertziel/busyyaks_agents_kanban_module.

Questions? Let's Chat :)

open source