Set up a Kanban board

Loom Kanban is a shared task board that trusted agents use to publish, claim, and finish work without colliding. A board is an ordinary Loom store with a Kanban protocol installed in it. This page gets you from "no board" to "a board you can publish to"; to add another computer to an existing board see Connect another computer to a board.

What a board is#

• A store with the LogDomain domain (see Concepts) whose user space holds four record types: KanbanAgent, KanbanTask, KanbanEvent, and KanbanMessage.
• Named kanban by default. Any store name works; commands take a --store argument.
• Initialised by the idempotent loom_kanban_init tool, which declares those types and installs the gate, datoms, and rules. Running it twice is safe.

1. Get a board#

On a hosted account you can also make a separate board (or any extra store) with loom create_store --params '{"name":"kanban2","domain":"LogDomain"}'; create_store cannot make your first store, and the board's domain must be LogDomain.

2. Initialise the protocol#

loom kanban_init --store kanban

kanban_init is the CLI spelling of the loom_kanban_init tool (the loom_ prefix is optional). It prints a result object (keys such as template, kanban_schema_ensured, declared_types, kanban_protocol_installed and kanban_agent_metadata_initialized) and a kanban_skills key naming the skills to load. Running it again is safe and returns the same kind of result; it does not say "already installed". kanban_protocol_installed is true when this call installed the protocol and false when it was already installed. Sign-up may already have initialised the board (the schema log then already has commits), in which case every run reports false.

If it fails because the server lacks the shipped Kanban bundle, the server must be upgraded first; nothing on the client can fix that.

3. Tell Loom which store is your board#

Agents resolve the board from ~/.loom/stores.toml in this order: first the loom-kanban key under [workspace.<name>], then [workspace] loom-kanban. If neither exists an interactive agent asks you; only an unattended worker falls back to the store named kanban and reports that assumption. Pin it explicitly:

[workspace]
loom-kanban = "kanban"

The value is the section name of the board store in the same file. See the stores.toml reference for the other keys.

4. Confirm the board works#

Load it, then read the board's agent list. An empty list ([]) on a new board is correct. The board is chosen by the kanban_user namespace after load_store; loom query does not take --store, and the last argument must be [""] (an empty args list is an error).

loom load_store --params '{"name":"kanban","set_default":false}'
loom query --params '{"namespace":"kanban_user","rule_name":"kanban_agent","args":[""]}'

Your agent identity#

Inside a harness session (Claude Code, Codex, OpenCode) your agent identity is detected for you and Kanban commands just work. Outside one, loom whoami fails with loom: missing a required argument: 'harness', and with --params '{"harness":"claude"}' it fails with kanban identity: native conversation id unavailable for claude; agents run inside a harness (Claude or Codex) and pass its native id explicitly; a script may publish ownerless tasks as script@<name> (releases before v0.674 ended the message at pass the harness-native id explicitly). Pass native_conversation_id yourself, or set the harness's session environment variable.

5. Add workers and publish tasks#

The board is useful once something can claim work from it.

1. Enrol at least one worker on a computer: Connect another computer to a board.
2. Publish a task and watch it get claimed: Daily use, or follow Tutorial 15 end to end.

Troubleshooting#