The task board & swarm

The task board is the operator’s Kanban: a docked board where each card is a unit of work. It’s how you queue up work, hand it to panes, and — with the drainer — let Loom run a whole queue as a swarm.

Cards

A card is a launch spec plus an optional prompt:

• --command — what to run (default claude).
• --prompt / -p — an optional prompt to brief the launched agent.
• --workspace / -w — which workspace it belongs to (defaults to your pane’s workspace).

loom card add "Migrate auth to v2" -p "port src/auth to the v2 API and run the suite"
loom card list
loom card move card3 done

• card add returns the new card’s id.
• card list shows id, title, and status.
• card move <id> <todo|done|failed> moves a card between lanes.

Cards live in the repo

Board state is project-scoped, stored in the project’s own .loom/board.json (keyed by the workspace’s folder). So cards travel with the repo and survive reopening — the board isn’t a transient UI list, it’s part of the project.

Who does what

• Only the operator dispatches a card into a pane (from the UI). An agent can create, list, and move cards — but it can’t spawn a pane from one.
• A worker closes its own card. When an agent finishes, it runs loom card move <id> done — that’s the swarm payoff: work reports its own completion.
• Dispatched cards self-close too. A card that was dispatched into a pane auto-moves to Done or failed when that pane’s task ends, so you don’t have to babysit the ones the agent’s own signals already cover.

Swarm the queue — drain

loom card drain on --cap 4     # keep 4 panes busy from the To-do lane
loom card drain off            # stop dispatching

drain arms the board’s auto-drainer. While it’s on, Loom keeps dispatching the top To-do cards into fresh panes until the In-progress lane reaches --cap (default 3), then refills a slot each time a card finishes. This is the swarm loop: unlike a single card move, it lets an agent launch work, not just queue it.

# The typical swarm: queue a batch, then let it drain
loom card add "Port module A" -p "…"
loom card add "Port module B" -p "…"
loom card add "Port module C" -p "…"
loom card drain on --cap 3

Two safety properties worth knowing:

• A dispatched card holds its slot until it leaves the lane, so a non-reporting agent or plain shell won’t get double-dispatched. (The operator frees a stuck slot with the ✓ in the UI.)
• Drain is session-only — it’s never persisted, so it won’t silently re-arm when you reopen the project.

From an agent (MCP)

The same operations are available as MCP tools — card_add, card_list, card_move, card_drain — defaulting to the caller’s workspace. See Agents, MCP & hooks.