Getting Started

Welcome to Watchflows

Watchflows is a visual workflow automation tool for macOS. It lets you connect triggers, conditions, actions, and AI nodes on an infinite canvas to automate tasks on your Mac. Everything runs locally, no account required.

Workflows are built by placing nodes on a canvas and wiring them together. When a trigger fires, data flows through the chain as a payload, and each node along the way can read, transform, or act on that data.

Creating Your First Flow

From the home screen, click the + New Flow button. This creates a new workflow and opens the visual canvas where you will build your automation.

The canvas is an infinite workspace. You can pan by scrolling or dragging the background, and zoom with pinch or the scroll wheel. Nodes snap to a grid to keep things aligned.

Adding Nodes

The node library lives in the sidebar on the left. Browse the categories or use the search field to find a specific node. Drag any node from the library onto the canvas to add it to your workflow.

There are several categories of nodes, each with a distinct color:

• Triggers start your workflow. They monitor for events like file changes, schedules, keyboard shortcuts, webhooks, and more. Every flow begins with a trigger.
• Conditions route data based on comparisons. A condition node has a Yes outlet and a No outlet, so your flow can branch depending on the payload values.
• Actions perform operations such as sending notifications, running scripts, making API requests, moving files, and controlling other apps.
• AI Nodes use language models to transform, classify, summarize, or analyze data flowing through your workflow. Connect a local model or an OpenAI-compatible endpoint.
• Transformers reshape data with templates, loops, math operations, and key mapping.
• Utilities help you debug and observe your workflow with breakpoints, logs, JSON viewers, and timers.

Connecting Nodes

Each node has ports on its edges. Outlet ports sit on the right side of a node and inlet ports sit on the left. To connect two nodes, click and drag from an outlet port to an inlet port. A wire will appear linking them together.

When the workflow runs, data flows along these wires from left to right. The payload created by the trigger travels through each connected node in sequence.

To remove a connection, select the wire and press Delete. You can also drag a wire's endpoint to a different port to rewire it.

Configuring Nodes

Click any node on the canvas to select it and open the inspector panel on the right side of the window. The inspector shows the node's configuration fields, which vary by node type.

Text fields in the inspector support variable interpolation. Type {{variableName}} to reference values from the payload. As you type, Watchflows shows available variables from upstream nodes so you can insert them without memorizing names.

See the Payloads documentation to learn more about how data flows between nodes.

Running Your Flow

Click the Run button in the toolbar to manually execute your workflow. Watchflows will fire the trigger with sample data and process each node in order.

As the flow executes, you will see animated highlights on each node and wire as data passes through them. Nodes that complete successfully show a green check, while nodes that encounter an error show a red indicator. Click any executed node to inspect the payload it received and produced.

Manual runs are the fastest way to test and iterate on your workflow before arming it to run automatically.

Arming Triggers

Once your workflow is working the way you want, toggle the Triggers switch in the toolbar to activate it. When armed, the trigger actively monitors for its event in the background. Every time the event occurs, the workflow executes automatically.

Armed workflows run even when the canvas is not open. A background agent monitors all armed triggers and fires the appropriate flows as events happen on your system.

To stop automatic execution, toggle the Triggers switch off. You can still run the flow manually at any time. If you've paused all triggers from the home page, arming a flow here turns triggers back on for every enabled flow.

Organizing with Folders

As you build more workflows, folders help keep things organized. Right-click on the home screen to create a new folder. Give it a name and an optional accent color to visually group related flows.

Drag flows into folders to organize them by project, category, or whatever structure makes sense for you. Flows can be moved between folders at any time.

Star your most-used flows to mark them as favorites. Starred flows appear at the top of the home screen for quick access.

Getting Help

Watchflows includes built-in documentation you can access at any time. Open the Help menu to browse the full documentation site locally.

Each node type also has a ? button in its inspector panel. Clicking it opens the documentation page for that specific node, where you will find details on its configuration options, input and output variables, and usage examples.

To learn more about key concepts, explore the sidebar links for Payloads, Port Types, AI Providers, and the Execution Model.