Workflows addon

Workflows is an optional addon. The viewer (threadle, :4570) stays the product. The addon (threadle-workflows, :4571) is a separate app for graphs, gates, recipes, and headless runs. Shared state lives under ~/.config/threadle. UI paths sit under /addon/workflows.

Soft-frozen: fix breakage only. Prefer recipes, examples, and custom nodes over new built-in verbs.

A workflow is a small number of ideas that compose: wires move text, ▶ Run walks dependency order, agents spawn real sessions on disk. You do not need the canvas to use threadle. Most people live in Sessions and only open the addon when a job should be repeatable.

When you need it

Use the addon when a job should be repeatable:

the same plan → implement → review loop across providers
an approval or spend ceiling before agents continue
a recipe you re-run from the CLI or MCP
a brief pipeline that ends in a result, not a one-off chat

If you only need to inspect sessions, blueprints, spend, or handoff, stay in the viewer. See Sessions · Tour.

Step	Page	You can…
0 · See (viewer)	Sessions	Browse sessions, blueprints, spend. No wiring (~5 min)
1 · Canvas basics	Getting started	Wire nodes, run an agent, gate a result, parameterize (~20 min)
2 · Shapes	Patterns	Merge, judge, iterate, breakers, parallelism, headless (~45 min)
3 · Runs	Running	▶ vs ≫, Issues, partial runs, gates and splice
4 · Jobs	Recipes · Examples	Clone teaching graphs or outcome-first jobs
5 · Extend	Custom nodes · Portable graphs	Your nodes, sub-workflows, export

Start the app

threadle-workflows                       # editor + runner (:4571)

From the viewer: sidebar Workflows (addon badge), or Settings → Addons → Workflows. Graph links and “send to workflow” open the addon in its own tab.

What lives here

Surface	Role
Workflows	Saved graphs, examples, recipes, import/export
Canvas	Wire agents, prompts, gates, context
Runs / Logs	Job history and streams for workflow and agent jobs
Nodes	Custom nodes you install or author
CLI / MCP	`threadle run …`, detached jobs, graphs as tools

Mental model

Nodes join by wires. ▶ Run sorts the graph into dependency order and runs each node when its inputs are ready. Agents spawn real provider sessions on disk. Approvals and circuit breakers in park mode stop for a human splice. Params make the same graph reusable from UI or CLI:

threadle run hello
threadle run plan-implement-review --param task="…" --approve-all

Send to workflow from the viewer seeds a new graph anytime: session / project → workflow, blueprint → workflow, library use in workflow. That opens the addon on the fresh graph with context already wired where it applies.

Examples and recipes

Examples teach one mechanic each (merge, judge, detached delay, …). Recipes are workflows packaged as jobs with an explicit contract (model, --dir, session slot). Both live under Workflows in the addon UI.

Clicking an example clones it into your library — your editable copy, not a read-only demo. The same graphs run from the terminal:

threadle --list-templates
threadle run hello --approve-all
threadle recipes

Cost while learning: beginner and most intermediate examples are agent-free (prompts, converters, merges, iterators, breakers). You only spend when you wire an agent node. Tracked costs vs actual spend shows list price vs what left your pocket.

Guides in this section

Page	Use when
Getting started	First wires: prompt, agent, approval, params, send-from-viewer
Patterns	When to use judge, merge, iterator, tripwire, parallelism, err port
Running	▶ vs ≫, readiness, Issues, partial runs, gates
Detached runs	Close the browser, `threadle jobs` / `attach`
Portable graphs	Export / import `threadle/graph@1`
Examples	Cloneable teaching graphs
Recipes	Job graphs that end in a result
MCP	Expose saved graphs as tools

Hold rules and package layout also live in the app repo as docs/workflows.md.

Recipes worth opening first

Recipe	What it does
`plan-implement-review`	Plan → implement → review spine with a `task` param
`best-of-n`	N agents attempt, a judge picks
`diff-review-panel`	Several reviewers, one verdict
`handover-brief`	Today’s context shaped for tomorrow’s start
`repo-brief`	New-contributor brief for a repo

threadle recipes
threadle run best-of-n --param task="…" --approve-all

Full table: Recipes.

Extending the canvas

Custom nodes, named ports, and the stdlib pack live under Extend in the docs (and Nodes in the addon UI). The Guarded parallel fan example (parallel agents, per-branch breakers, merge, splice, spend ceiling) is the expert composite — open it after Patterns clicks.

Getting started · Patterns · Recipes