parallel

NAME

parallel - execute multiple tasks concurrently

SYNOPSIS

state-name:
  tool: parallel
  arguments:
    tasks:
      - tool: <tool-name>
        arguments:
          <arg>: <value>
        output: <destination>  # optional

DESCRIPTION

The parallel tool executes multiple tasks simultaneously, improving workflow performance when tasks are independent. Each task runs in its own thread with isolated output capture.

All tasks start at the same time. The parallel block completes when all tasks finish. If any task fails, the first non-zero exit code is returned after all tasks complete.

ARGUMENTS

Argument	Required	Default	Description
`tasks`	Yes	-	Array of task definitions

Task Definition

Each task mirrors a state definition:

Field	Required	Default	Description
`tool`	Yes	-	Tool to execute
`arguments`	Yes	-	Tool arguments
`output`	No	-	Output capture destination

EXIT CODES

Code	Meaning
`0`	All tasks succeeded
Non-zero	First failed task’s exit code

OUTPUT

Each task can capture output independently:

gather-data:
  tool: parallel
  arguments:
    tasks:
      - tool: bash
        arguments:
          command: curl https://api1.example.com
        output: var(api1)
      - tool: bash
        arguments:
          command: curl https://api2.example.com
        output: file(./api2.json)

The parallel tool itself does not produce output for capture.

EXAMPLES

Basic Parallel Execution

run-parallel:
  tool: parallel
  arguments:
    tasks:
      - tool: bash
        arguments:
          command: npm run lint
      - tool: bash
        arguments:
          command: npm run typecheck
      - tool: bash
        arguments:
          command: npm test

With Output Capture

fetch-all:
  tool: parallel
  arguments:
    tasks:
      - tool: bash
        arguments:
          command: curl -s https://api.example.com/users
        output: var(users_json)
      - tool: bash
        arguments:
          command: curl -s https://api.example.com/orders
        output: var(orders_json)
      - tool: bash
        arguments:
          command: curl -s https://api.example.com/products
        output: file(./data/products.json)
  next: process-data

Parallel AI Queries

get-perspectives:
  tool: parallel
  arguments:
    tasks:
      - tool: claude
        arguments:
          prompt: "Review this code: {{ file(./src/main.ts) }}"
        output: var(claude_review)
      - tool: gemini
        arguments:
          prompt: "Review this code: {{ file(./src/main.ts) }}"
        output: var(gemini_review)
  next: compare-reviews

Error Handling

parallel-tasks:
  tool: parallel
  arguments:
    tasks:
      - tool: bash
        arguments:
          command: ./task1.sh
        output: var(result1)
      - tool: bash
        arguments:
          command: ./task2.sh
        output: var(result2)
  on-error:
    _: handle-failure
  next: all-succeeded

handle-failure:
  tool: bash
  arguments:
    command: |
      echo "One or more parallel tasks failed"
      echo "Task 1 result: {{ result1 }}"
      echo "Task 2 result: {{ result2 }}"

Test Sharding

run-tests:
  tool: parallel
  arguments:
    tasks:
      - tool: bash
        arguments:
          command: npm test -- --shard=1/4
        output: var(shard1)
      - tool: bash
        arguments:
          command: npm test -- --shard=2/4
        output: var(shard2)
      - tool: bash
        arguments:
          command: npm test -- --shard=3/4
        output: var(shard3)
      - tool: bash
        arguments:
          command: npm test -- --shard=4/4
        output: var(shard4)
  next: merge-results

Parallel Sub-Flows

process-shards:
  tool: parallel
  arguments:
    tasks:
      - tool: sub-flow
        arguments:
          workflow: process-shard
          variables:
            shard_id: "1"
      - tool: sub-flow
        arguments:
          workflow: process-shard
          variables:
            shard_id: "2"
      - tool: sub-flow
        arguments:
          workflow: process-shard
          variables:
            shard_id: "3"

RESTRICTIONS

Interactive tools cannot be used in parallel:

claude-code - Requires terminal
ask-user - Requires user input

These tools will cause validation errors if included in a parallel block.

EXECUTION MODEL

All tasks start simultaneously
Each task runs in isolation
Output capture is independent per task
All tasks run to completion (even if one fails)
Exit code is the first non-zero, or 0 if all succeed

PERFORMANCE

Parallel execution can significantly reduce workflow time for independent tasks:

Sequential: Task1 (5s) → Task2 (3s) → Task3 (4s) = 12s total
Parallel:   Task1 (5s) + Task2 (3s) + Task3 (4s) = 5s total (limited by slowest)