# AI Flow Builder

Chat with the canvas. Describe what you want in plain English — “when a file lands in Downloads, move PDFs to my Documents folder” — and watch the nodes appear and wire themselves together. Keep chatting to refine what's there.

You describe it

Plain-English request in the chat

↓
Your AI provider plans it

Validated against real node types

↓
It builds on the canvas

Nodes appear and wire up live

## 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 Provider

Connect an AI provider

2 Open a flow

Create a new, empty flow

3 Describe it

Type what you want, hit return

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

The fastest on-ramp: OpenRouter

Create an OpenRouter account, drop in about $5 of credit, and copy an API key. Paste the key into Watchflows under Settings → AI Providers and you're running — with access to a wide range of capable models through a single key. (Local models are free if you'd rather keep everything on-device; they just need to be downloaded and running first.)

### 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:

Builder enabled

On by default

AND

Provider configured

At least one in Settings

↓

Chat appears

Ready to build

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.

If validation can't be satisfied, nothing changes. A failed build leaves your canvas exactly as it was — it never drops a half-broken flow on you.

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.

### Use a capable model

A larger frontier model (easy via OpenRouter) plans more accurately than a small local one. If a build looks off, a better model is the biggest single upgrade.

### Name the whole outcome

Say the trigger, the source, and the destination: “When a PDF lands in ~/Downloads, move it to ~/Documents/PDFs.” Specifics beat adjectives.

### Build in steps

Start simple, then refine in follow-ups (“now add a notification,” “only for files over 10 MB”). Iterating beats one giant prompt.

### Answer its questions

If it asks, the detail matters. A one-word reply usually unblocks the build.

### Read the checklist

Fill in any placeholders and confirm destructive nodes before you arm the flow — that's the difference between “built” and “ready.”

### One flow per idea

The chat edits the open flow. Open a fresh, empty flow when you start something new so the builder isn't refining the last one.

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.