Parallelism
Parallelism is the maximum number of independent ready nodes that may execute at once. Default 4.
Set it in ≔ params → parallelism on the workflow.
In yarn, ply is how many strands twisted together. Here it is how many branches run side by side. The plain idea is a concurrency ceiling.
Parallelism 3: all three agents occupy one wave, so the wall clock is the slowest of them rather than their sum. Any of the seven providers can fill those slots. A merge brings the branches back to one value.
How waves work
Section titled “How waves work”The runner repeats three steps until the graph is done:
- Find every node whose predecessors have all completed. The ready set.
- Execute up to the configured parallelism of them concurrently.
- Check the graph spend ceiling, then form the next wave.
So parallelism doesn’t reorder anything. Dependencies are still respected exactly. It only decides how many already-eligible nodes may work at the same time.
When it matters
Section titled “When it matters”If A fans out into B and C, both become ready the moment A finishes:
| parallelism | Behavior |
|---|---|
1 | B runs, then C. Wall clock is their sum |
2 or more | B and C run together. Wall clock is the slower of the two |
For agent nodes, each one is a separate CLI process and a separate session, so the saving is real: three agents that take 2, 3, and 5 minutes finish in 5 minutes instead of 10.
The same ceiling also bounds ∀ Iterator when map mode is parallel: one fresh agent session per item, at most ply in flight. Join with a Merge. The iterator does not auto-join. See Iterator.
Choosing a value
Section titled “Choosing a value”| Situation | Suggested |
|---|---|
| Debugging a graph, want a readable log | 1 |
| Typical multi-agent fan-out | 2–4 (default 4) |
| Many cheap local custom nodes | higher is fine |
| Rate-limited provider, or heavy local CPU | lower |
Parallelism is a ceiling, not a target. A graph with no parallel branches runs identically at any setting.
Interaction with cost
Section titled “Interaction with cost”Concurrency and budgets pull against each other: several agents can be mid-flight when the ceiling is reached. threadle checks the graph spend ceiling between waves, so a run can overshoot by at most the wave that was already in flight. Per-branch circuit breakers still fire inside a wave, on their own wire.
Example
Section titled “Example”Parallel fan + majority merge. Two Cursor asks in parallel, merged by a majority merge, with a duration fuse watching the clock.
threadle run ply-fan-knot --approve-allRelated
Section titled “Related”- Merging. Bringing parallel branches back together
- Graph & wires. The wave loop
- Circuit breakers. Limits that survive parallelism