Quickstart

This walks you from a blank canvas to a running agent pipeline. No prior canvas experience assumed.

Prerequisite: threadle running at http://127.0.0.1:4570 — see Install.

---

1. Wire two nodes

Open Workflows → new workflow. You get an empty canvas.

1. Double-click empty canvas — the add-node menu opens.
2. Add a ✎ Prompt node. Type anything into it: Say hello in three words.
3. Drag from the prompt’s right-hand handle and drop on empty canvas. The wire-drop menu opens, filtered to nodes that can accept text.
4. Pick ⇤ Output.
5. Press ▶ Run.

The output node fills with the prompt text. That run is a server job — you can close the tab and reopen the workflow to see the result. Nothing called a model: a wire moves text, and Run walks the graph in dependency order.

Tip

Prefer to read rather than build? Workflows → Examples → Hello wire clones exactly this graph. Every example in the table is a working, runnable graph you can open and take apart. From a terminal (with the server up): threadle run hello-wire --detach then threadle jobs.

---

2. Put an agent in the middle

Now make it do real work.

1. Delete the wire (click it, press Delete).
2. From the palette’s Agents tab, drag an agent definition onto the canvas — any Claude, opencode, or Cursor agent threadle discovered.
3. Select the agent node and pick a model in the inspector. This is required: a run refuses to start without one.
4. Wire prompt → agent → output.
5. ▶ Run.

threadle spawns a real session through that provider’s CLI. Watch the Run log at the bottom. When it finishes, the output node holds the agent’s reply, and a session node appears wired to the agent — that conversation now exists on disk like any other, and the next run continues it.

---

3. Add a human checkpoint

Insert a gate so you see the text before it moves on.

1. Add a ✓ Approval node between the agent and the output.
2. ▶ Run again.

The run parks. The dock shows the agent’s text in an editable box — fix a word, delete a paragraph, whatever you like. Approve · continue forwards your edited version. That edit-in-place is called a splice.

---

4. Make it reusable with a param

Hard-coded prompts age badly.

1. Open ≔ params in the topbar and add a param named task, type text.
2. In the prompt node, replace your text with: Review this and list three risks: {{param:task}}
3. ▶ Run — threadle asks for task before starting.

The same graph now runs against anything. Params are also how the CLI drives a workflow:

threadle run <graphId> --param task="the auth refactor" --approve-all

---

5. Protect the run

Before you let a graph loose unattended, give it a limit.

• In ≔ params, set a spend tripwire — the whole run aborts if tracked cost crosses your ceiling.
• Or drop a ‡ Tripwire node on a wire for a per-branch rule: trip on an empty or too-short result, on a regex match like ERROR, on elapsed time, or on tokens. Choose what happens when it trips: abort, skip the branch, or park for a human.

See Tripwire.

---

What you just learned

Step	Concept
1	Nodes, wires, topological run order
2	Agent nodes, models, result sessions
3	Gates and splicing
4	Params and CLI reuse
5	Circuit breakers and spend ceilings

---

Next

• Learning path — the ordered route from here to expert
• Tour of the app — what every view is for
• Examples — 17 runnable graphs, beginner to expert
• Recipes — job graphs (diff review, handover, repo brief)
• Graph & wires — the execution model in depth