beads-loop

Beads Loop Command

Execute beads iteratively until all ready tasks are complete.

Note: Loop and swarm are interchangeable - swarm is just faster when tasks can run in parallel. Both enforce exit criteria and sync beads.

Uses Claude Code's built-in Task Management System for dependency tracking and visual progress (ctrl+t).

Arguments

• --label <label> (optional): Filter beads by label (default: ralph)
• --max-iterations N (optional): Maximum iterations before stopping (default: unlimited)

Instructions

Step 1: Load Beads (Only)

DO NOT read files, grep, or explore the codebase - just get beads from CLI. Never spawn sub-agents or delegate work — do ALL implementation directly yourself.

bd list --status open --json
# Or with filters:
bd list -l <label> --status open --json

Parse the output to get all beads.

Step 2: Create Task Graph

Create a task for each bead and build an ID map as you go:

// Create tasks in order — each returns a task ID
TaskCreate({ "subject": "beads-abc123: Setup types", ... })      // → task "1"
TaskCreate({ "subject": "beads-def456: Implement auth", ... })   // → task "2"
TaskCreate({ "subject": "beads-ghi789: Add routes", ... })       // → task "3"

// ID map: { "beads-abc123": "1", "beads-def456": "2", "beads-ghi789": "3" }

Full TaskCreate per bead:

TaskCreate({
  "subject": "beads-abc123: Implement login form",
  "description": "<full bead description - self-contained>",
  "activeForm": "Implementing login form",
  "metadata": { "beadId": "beads-abc123" }
})

Translate bead dependencies to addBlockedBy using the ID map. Extract depends_on from bd list --json output:

// bd list shows: beads-ghi789 depends_on ["beads-abc123", "beads-def456"]
// ID map: beads-abc123→"1", beads-def456→"2", beads-ghi789→"3"
TaskUpdate({
  "taskId": "3",
  "addBlockedBy": ["1", "2"]
})

A task with non-empty blockedBy shows as blocked in ctrl+t. When a blocking task is marked completed, it's automatically removed from the blocked list. A task becomes ready (executable) when its blockedBy list is empty.