AI Flow Builder

What It Is

The Flow Builder is a chat box that lives on the canvas itself. 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 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, a Spotlight-style chat capsule sits in the middle of the canvas, with a few example prompts you can tap to try.

3. Describe what you want

Type the outcome in plain English and press return. The builder plans the flow, then the nodes animate into place and wire themselves up. As soon as you send your first message — or there are nodes on the canvas — the chat tucks into a small bar at the bottom so you can keep refining.

Turning It On or Off

The toggle lives under Settings → AI & Services → AI Flow Builder (“Enable the AI Flow Builder”). It's on out of the box. Turning it off hides the chat capsule entirely — the rest of the canvas works exactly as before. Two conditions decide whether the chat appears:

No provider, no chat — the capsule only shows up once a provider exists. If you've enabled the builder but don't see it, that missing provider is almost always why.

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

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.

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.