Patterns

Practical shapes once Getting started clicks. Use this page to pick the right node before you wire. Teaching graphs are under Examples; outcome-first jobs under Recipes.

Most teaching examples are agent-free. Anything that calls a provider CLI costs tokens. Set a spend ceiling first on multi-agent or unattended graphs.

When to use what

You need…	Reach for…	Not…
Combine several inbound texts deliberately	⋈ Merge with a strategy	Several wires into one node (silent blank-line join)
Route text to different paths by content	? Judge (pass / fail / unsure)	A circuit breaker (that is “stop or continue on this wire”)
Stop or park when output is bad or spend is high	‡ Circuit breaker or graph spend ceiling	Judge (that is “which path?”)
Human edit before continue	✓ Approval or breaker park	`--approve-all` when you need splice
Loop a body N times or until exhausted	↻ Until on re-entry	A free cycle (the graph must stay a DAG)
Wait for a session to finish generating	◌ Wait for idle	Polling with delay nodes alone
Run the same downstream once per line or JSON item	∀ Iterator	Copy-pasting the subgraph
Many items at once, separate sessions	Iterator parallel + Merge fan-in	Serial iterator when items must share one session
Several ready nodes at once	Parallelism in ≔ params	Expecting unbounded concurrency
Recover from agent failure without aborting	err port (`out:err`) + fallback arm	Continue-on-error alone when you need the error text
Skip editing the graph	Mute (skip) or Bypass (pass-through)	Deleting nodes and rewiring
Re-run only the tail of a pipeline	Run from / detached `scope`	Full ▶ every time
Run with browser closed	≫ / `--detach` + `--approve-all`	In-tab ▶ with approval gates

Detached jobs

A server job keeps running after you close the tab:

threadle --no-open
threadle run detached-delay --detach
threadle jobs
threadle attach <jobId>

Reopen the workflow later. Statuses and outputs sync from the job. Agent-free Detached delay (~60s) is the teaching run. See Detached runs · CLI.

Branching and merge

Fan-out: one node can feed several. Wire a prompt into two converters and both fire. The graph is a DAG, not a line.

Fan-in: several wires into one node join with blank lines by default. That is fine for two short strings and easy to regret later. Prefer an explicit ⋈ Merge:

Strategy	Use when
`concat`	You want labeled sections or a fixed separator
`first`	Only the first arrival matters
`majority`	Several agents answered the same question — vote
`synthesize`	You want one written summary (optionally run a model on the merge node)

majority and synthesize turn “ask three agents” into “one answer”. Multi-provider fan-out (Claude + opencode + Cursor on one canvas) is the interesting case.

▶ Examples: Merge concat, Merge first-wins. See Merging.

Judge, Until, Wait for idle

Judge

A ? Judge routes by ordered regex / contains matchers. First hit wins. Outs: pass · fail · unsure. Unmatched text can emit on unsure or park for splice. Only one arm continues; losing ports stay empty.

Use Judge when the question is “which path should this text take?”

Prefer a circuit breaker when the question is “should this run stop, skip, or park on this wire?”

Cycles (fail → fix → back) are not free loops. Use ↻ Until for counted re-entry: body runs until iterations exhaust, then the exhausted out fires. Keep the fix path linear, or wire Judge fail → Until → reenter body.

▶ Examples: judge-branch, until-reenter, wait-idle-gate. See Judge · Until · Wait for idle.

Wait for idle

Wait for idle parks until a watched session stops generating (or times out). Use it when the next step must not start while the provider is still streaming.

Iterator

An ∀ Iterator splits inbound text into items: lines, blank-line blocks, or a JSON array (optional cap). Downstream runs once per item.

Mode	Use when
serial (default)	One linked session; context accumulates across items
parallel	Fresh session per item, bounded by graph parallelism, then fan-in with Merge

This is how a checklist becomes N agent runs without N copies of the graph. After an agent per item, wire a content circuit breaker to catch empty replies on item 7.

▶ Examples: Iterator lines, iterator-parallel, Iterator → agent. See Iterator.

Mute and bypass

Toggle	Effect
Mute	Node skipped. Downstream starves
Bypass	Node does not execute. Inbound text passes through

Bypass is how you A/B a converter or pull an agent out of a chain without deleting wires. Starter workflow (plan-implement-review) uses a muted optional skill node you can enable later.

▶ Example: Mute & bypass

Approval, park, and splice

Insert ✓ Approval between agent and output (or anywhere you need a checkpoint). The run parks. Edit the dock text, then approve. Downstream gets your version (splice). Reject stops the run.

Circuit breakers in park action use the same editable dock as approval — useful for “regex matched ERROR, human decides”.

Run mode	Splice?
In-tab ▶ with approval / live-handoff	Yes — edit before continue
≫ / `threadle run … --approve-all`	Auto-pass; inbound text forwarded unchanged

Prompt → agent → approval gate → output

▶ Example: splice-gate (--approve-all auto-passes when detached). See Gates · Running.

Circuit breakers and spend ceilings

A ‡ circuit breaker watches a wire:

Mode	Trips when
`content`	Empty, too short, or regex match / miss
`spend`	Run spend crosses a dollar threshold
`retries`	Run failure count crosses a threshold (pair with err port / continue-on-error)

Action	Effect
`abort`	Stop the run
`skip`	Fail this node, starve the branch
`park`	Pause for a human (same dock as approval)

A content breaker that parks on /ERROR/ is a cheap quality gate.

Also set a graph-wide spend ceiling in ≔ params. Checked between parallel waves — spend cannot outrun the ceiling by more than one wave.

▶ Examples: Content breaker, Min-chars breaker, Spend ceiling. See Circuit breakers.

Parallelism and fan-out / fan-in

Parallelism (default 4 in ≔ params) is how many independent ready nodes may run at once. The runner works in waves: all nodes whose predecessors finished become ready; up to N run together. With parallelism 1, a fan-out serializes. With 3, three agents run together and wall clock follows the slowest branch.

Workhorse shape:

prompt ──┬─▶ agent A ──┐
         ├─▶ agent B ──┼─▶ ⋈ merge (majority) ──▶ ✓ approval ──▶ ⇤ output
         └─▶ agent C ──┘

Change merge to synthesize with a model on the node for a written verdict instead of a vote.

The Guarded parallel fan example stacks parallelism, per-branch breakers, merge, splice, and a graph spend ceiling — read it when the above shapes are familiar.

▶ Example: Parallel fan + majority merge. See Parallelism.

Plan → implement → review

Bundled spine: plan with one agent, implement with another, review with a third, gated by approvals, driven by a task param. Optional skill invoke demo: Skill invoke + Judge (threadle run skill-invoke-judge). See Skills & rules.

threadle run plan-implement-review --param task="fix the flaky auth test" --approve-all

Also see Recipes for job graphs (diff review, handover, repo brief, best-of-n).

Partial runs

Right-click a node:

Run from this node. That node and everything downstream
Test this node. Just that one

Nodes outside the scope contribute last known result read-only (prompt text, saved output, materialized payload, agent session tail). Fix stage four of five without re-paying for stages one and two.

Run from confirms counts: re-run · reuse · missing. Server jobs can pass scope and optional replayFromJobId. See Running.

Errors and the err port

Per node: retry (off / 1× / 3× with backoff) and continue on error. With continue-on-error the node goes red, the run continues, and downstream may starve.

Agent nodes expose a lower err connector (out:err): wire fallback convert or Judge arm; failure text flows there after retries. Unwired err keeps halt / starve behavior. Hover the port for err · after retries exhausted.

Pair retries circuit breaker mode with flaky steps: tolerate two failures, abort on the third.

▶ Example: agent-err-fallback. See Errors & retries.

Headless runs

Same executor from the terminal:

threadle run <graphId|template|file.json> \
  --param task="..." \
  --approve-all \
  --dir ~/code/my-project

threadle run <id> --watch --approve-all --dir .
threadle open skills
threadle open session cursor:abc123
threadle daemon

Detached rules:

Interactive gates need --approve-all (or ≫). Use in-tab ▶ when you need splice.
Context nodes need a session source or a Library payload. Detached jobs refuse a bare ❝ with neither.

Check threadle services before a long unattended batch. See Detached runs · Triggers & daemon.

Read the dock

Tab	Role
Run log	Order, timing, token and spend lines, breaker evaluations
Issues	Hard blockers for ▶ / ≫ (model, wiring, cycles)
Graph lint	Soft lint — dangling outputs, unused params — never blocks

Issues block a run. Graph lint does not. See Bottom dock · Graph lint.

Extend the canvas

When built-in verbs are not enough:

Custom nodes — your code or command on the canvas
Params & named ports — widgets and multi-lane I/O
Frames & sub-workflows — save a cluster, reuse as ▦ frame
Portable graphs — export threadle/graph@1, run elsewhere

Recipes · Examples · Portable graphs · Running