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. 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.
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