AI Flow Builder

What It Is

The Flow Builder is a conversation with the open flow. Instead of dragging nodes from the sidebar and wiring them by hand, you tell it the outcome you want and it assembles the workflow for you — choosing the trigger, the action nodes, and the connections between them. It runs on your default AI provider (set in Settings → AI Providers), so the intelligence comes from whatever model you've connected. Note it always uses your default provider — even if individual AI nodes in a flow are set to different ones.

It works two ways:

• Build from scratch. On an empty canvas, a request like “OCR my screenshots and save the text next to them” produces a complete, connected flow.
• Refine what's there. With nodes already on the canvas, follow-up messages edit the flow — “now send me a notification when it finishes” adds and wires the new node without rebuilding the rest.

The Flow Builder View

Every flow has two views of the same graph. A segmented switch in the flow's toolbar — Canvas | Flow Builder (or ⇧⌘B) — flips between them:

• Canvas is the hands-on view: the node palette in the left sidebar, drag-and-drop wiring, the inspector on the right — everything works as it always has.
• Flow Builder swaps the left sidebar for a conversation with the flow. The canvas stays fully live — nodes are still clickable and runs still animate — you're just steering with words instead of drags.

A few things about the conversation worth knowing:

• It's persistent. Each flow keeps its own transcript across window closes and app relaunches — roughly the last 200 turns, so “the OCR step we added last week” still means something. You pick up where you left off, not from a blank chat.
• Every build is a restore point. A build turn shows a short reply plus a collapsible plan card. Recent build cards (about the last 50) carry a snapshot of the graph as it stood after that turn — click Restore here on one to put the flow back exactly as it was. The restore is recorded as its own turn, and it's undoable like any other edit.
• Runs show up in the conversation. If the flow fires while you're in Flow Builder, the run lands as a quiet notice in the transcript (a burst of runs folds into one). Click it to open the execution history — runs themselves behave exactly as they do in Canvas view.
• The inspector stays out of the way. It's hidden by default and slides out over the canvas when you click a node; sending a message, pressing Esc, or deselecting tucks it away again. Flow-level settings (Lock this flow, Expose to AI agents) live behind the sliders button in the conversation header — those switches are yours alone; the builder can't flip them.

The Easiest Path to Get Started

The Flow Builder is on by default. The one thing it needs is an AI provider to think with. The quickest way to a working setup:

1. Connect an AI provider

Open Settings → AI Providers and add one. Any provider works — local models via Ollama or LM Studio, or a hosted one like OpenAI, Anthropic, Google Gemini, OpenRouter, or any OpenAI-compatible endpoint.

2. Open a new flow

Create a fresh, empty workflow. With a provider configured, an invitation sits in the middle of the canvas — a message box with a few example prompts you can tap to try. (You can also paste a screenshot or image there to build from.)

You don't even need to open a canvas first. When your Home screen has no flows yet — or a search or category filter hides them all — that same describe-a-flow box appears right on Home. Type what you want, press return, and Watchflows creates the flow and slides into the canvas already building it.

3. Describe what you want

Type the outcome in plain English and press return. Sending builds in Flow Builder — the left sidebar becomes your conversation, the builder plans the flow, and the nodes animate into place and wire themselves up. Keep refining from there, or flip back to Canvas in the toolbar whenever you want to work by hand.

When It Appears

There's no switch to flip — one condition decides whether the builder appears:

No provider, no builder — the toolbar switch and the invitation only show up once a provider exists, and they disappear again if you remove your last provider. If you don't see the builder, that missing provider is almost always why. And it never takes over: Canvas stays every flow's default view, so the builder is there when you want it and out of the way when you don't.

How It Works Under the Hood

The builder doesn't let the model touch your canvas directly. Every request runs through a pipeline that validates the AI's plan against the real node system before anything is drawn. That's what keeps it from inventing nodes that don't exist or wiring ports that can't connect.

1. 1 It reads the current canvas. The existing nodes and connections are summarized into a compact text snapshot. Fields the node marks as secret — passwords, bearer tokens, API-key auth values, webhook secrets — are masked to ••• before the summary is sent.
2. 2 It sends the model a catalog of real nodes. Along with your request, the prompt carries the actual list of available node types and a few worked examples. Node types that need an integration you haven't connected (Linear, say) are left out until you connect it, so the builder never proposes a step that can't work yet. The model is asked to reply with a structured plan, not free-form text.
3. 3 The plan is checked, op by op. Unknown node types and illegal connections are hard errors — a build can't contain them. Config fields are checked too (bad dropdown values, un-coercible numbers), but those surface as checklist warnings rather than failing the build. If the model gets something wrong, the exact error is handed back to it and it tries again — a couple of automatic repair rounds before it ever gives up.
4. 4 Only a valid plan is animated onto the canvas. Nodes spring into place, wires grow along their curves, and a short plan narration plays as it goes. Because every write was validated first, the flow arrives intact rather than half-formed — and it lands disabled, so nothing runs until you've reviewed it.

Two more things happen behind the scenes worth knowing about:

• It adapts to your model. Bigger, more capable models get the full node catalog; smaller local models get a trimmed version tuned to fit their context. Either way, the available options are preserved — a more capable model just builds more ambitious flows more reliably.
• A freshly built flow starts disabled. Watchflows runs a quick review and surfaces a checklist of anything that needs your attention — a blank field it couldn't guess (these block arming until you fill them in), or a destructive node like Delete File (flagged as a heads-up, then confirmed when you arm the flow). This is on purpose: the builder never quietly enables something that could delete files or run scripts.

It Asks When It's Unsure

When a request is missing a detail it genuinely needs — which folder, what file type — the builder pauses and asks rather than guessing wrong, sometimes with quick-reply buttons. Answering in the chat lets it finish the build. If it can't fill in a value at all, it leaves a clearly-marked placeholder in the node for you to complete, and that placeholder shows up on the review checklist.

In the Flow Builder view, blanks it needs from you often come with inline controls right in the conversation: a folder or file picker, a dropdown of the node's real options, a yes/no choice. Secrets get special handling — a password or API key is typed into a secure field, lands directly in the node's config, and appears in the transcript only as •••; the value itself is never shown in the chat or sent to the model. Settings too intricate for a chip get an Open config button that opens the node's inspector so you can finish it by hand.

Getting the Best Results

The builder is good, but a few habits make it noticeably better.

And remember the safety net: nothing the builder makes runs until you review and arm it — so if a build isn't what you pictured, there's no rush. Refine it with another message, or select the nodes and delete them and rephrase.

Diagnosing Failed Runs

The builder debugs, not just builds. When a run fails, open it in the execution history and click Diagnose — the flow switches into the Flow Builder view with the question already asked. (Or just ask the conversation yourself: “why did the recent failure happen?”) The builder reads the flow's recent run history (the same transcript you see in the timeline — the failing node and its error included), explains the likely cause, and can propose a fix as edits to the open flow. As always, nothing changes until you review and arm it.

Good to Know

• It builds and edits the graph — it doesn't run it. The Flow Builder assembles workflows for you to review and arm. (Separately, the AI Agents feature lets an assistant run the flows you choose to expose.)
• Your data goes to your provider. The canvas summary and your request are sent to whatever model you configured. Choose a local provider (Ollama, LM Studio) if you want every request to stay on your Mac. Fields marked secret (auth tokens, passwords) are masked first — but a key you type into a non-secret field, like a script body, request header, or JSON body, is not masked and will be sent as-is, so avoid hard-coding secrets there.
• Very intricate configs may need a manual touch. The builder handles the vast majority of node settings, including {{variable}} templates. A few deeply structured ones can be quicker to finish by hand in the inspector after it lays down the flow.
• New here? If you're still learning the pieces the builder is assembling, the Payloads and Port Types concepts — plus Getting Started — explain how the nodes it draws actually fit together.