Skip to main content

bloom run

Start the multi-agent orchestrator.

Usage​

bloom run

Description​

Launches the Terminal UI (TUI) and begins executing tasks with Claude Code agents. Multiple agents work in parallel on independent tasks.

Prerequisites​

  • Must be in a project directory
  • tasks.yaml must exist with valid tasks
  • Claude Code CLI installed and authenticated

Terminal UI​

┌─────────────────────┬─────────────────────┐
│ agent-1             │ agent-2             │
│ [implement-auth]    │ [create-ui]         │
│                     │                     │
│ > Creating JWT      │ > Building login    │
│   service...        │   form...           │
│                     │                     │
├─────────────────────┴─────────────────────┤
│ human                                     │
│ [q-abc123] Should I use bcrypt?          │
└───────────────────────────────────────────┘

TUI Controls​

KeyAction
hMove focus left
jMove focus down
kMove focus up
lMove focus right
EnterEnter focused pane (scroll)
Ctrl+BExit pane focus
rRestart selected agent
xKill selected agent
vToggle view (tiled/single)
qQuit orchestrator

How It Works​

  1. Find ready tasks — Tasks with ready_for_agent status
  2. Spawn agents — Launch Claude Code for each task
  3. Execute in parallel — Agents work in isolated worktrees
  4. Handle dependencies — New tasks become ready as others complete
  5. Collect questions — Human queue for agent questions

Execution Flow​

Task: todo
  ↓ (dependencies complete)
Task: ready_for_agent
  ↓ (orchestrator assigns)
Task: in_progress
  ↓ (agent completes)
Task: done

Custom Task File​

Run with a different task file:

bloom -f custom-tasks.yaml run

Monitoring​

While running, use another terminal:

# Live dashboard
bloom dashboard

# Task status
bloom list in_progress

# Agent status
bloom agents

# Specific task
bloom show <task-id>

Handling Questions​

Questions appear in the human pane. Answer via CLI:

bloom questions           # View pending
bloom answer q-id "response"  # Answer

Stopping​

  • Press q in TUI to quit
  • Tasks remain in current state
  • Run bloom run again to continue

Error Recovery​

Stuck Task​

# In TUI: press 'r' to restart
# Or:
bloom reset <task-id>

Failed Agent​

# Kill agent in TUI: press 'x'
# Reset task:
bloom reset <task-id>

Continue After Crash​

# Just run again - picks up where it left off
bloom run

Examples​

Basic Run​

cd my-project
bloom run

Monitor in Another Terminal​

# Terminal 1
bloom run

# Terminal 2
watch -n 2 bloom list

Answer Questions​

# Terminal 1
bloom run

# Terminal 2
bloom questions-dashboard