docs / 09

Flows: automations on a canvas

A flow is an automation you draw: something that starts it, then steps joined by wires. Data travels along the wires, and any setting can use it. Open flows in the taskbar.

A flow on the canvas: a schedule, a service, an AI step and a phone notification.

The easy way: describe it

Press + describe a flow and say what should happen, for example Every morning at 8, get the weather for Hyderabad and the dollar to rupee rate, write me a short note and send it to my Telegram. The Chef draws it and it opens on the canvas, unsaved.

Steps you should look at are marked [!] check: a credential to choose, a chat id to fill in, an address or a command. Click one to see why, and press Done when it is right.
The Chef never chooses a credential for you and never writes Code steps.
If something cannot be done with Kadhai's steps (there is no WhatsApp step, for example), it draws what it can and tells you what is missing.

Change it, fix it

Change it in words, in a flow's settings: also send it to my phone, only on weekdays at 7:30, stop writing the file. Only what you asked about changes; everything else keeps its place, credentials and settings. Changed steps are marked, nothing is saved until you press Save, and Ctrl+Z undoes it.
Fix it appears when a run stops at a failed step. The Chef sees the step, its error and what it received, and changes the flow so that it works. If the fix needs something only you know, it leaves that empty and asks you.

Try it before you trust it

Try once (next to Create) runs the flow as drawn without doing anything you could regret. Steps that only read or think run for real (weather, feeds, searches, reading a file, AI steps). Steps that would send, write, change, run a command or wait are held back, and show what they would have done, with the real data filled in.
In words, at the top of a flow's settings, describes the flow step by step and says how many model calls each run makes.

Drawing by hand

Drag a step in from the left, or press Tab on the canvas to search every step by name.
Drag from a step's output port to another step to wire them; drag onto empty canvas to add a step already wired in.
Shift+drag selects several; Ctrl+Z / Ctrl+Shift+Z undo and redo; Ctrl+C / Ctrl+V copy and paste steps; D switches steps off; Delete removes; Ctrl+S saves.
Pasting a curl command onto the canvas makes an HTTP step of it.
Every mouse action has a keyboard alternative, including wiring (the wire to... picker in a step's settings).

Seeing the data

Double-click a step for the large view: what it received on the left, its settings in the middle, what it produced on the right. Drag a field from the left onto a setting and it becomes an expression such as {{ input.title }}. Test step runs just that step. Pin keeps a step's output so it is not run again while you build what comes after (only for runs you start by hand). The runs tab shows the last 15 runs; click one to see it on the canvas.

Expressions. {{ input }} is what arrived, {{ input.items[0].url }} a field of it, {{ trigger.text }} what started the flow, {{ node('Fetch issues').body }} another step's output by name, {{ now }} and {{ today }} the time. Expressions are paths, never code.

What can start a flow

Start
By hand, every N minutes, or at a time of day	at least 5 minutes apart
A webhook	a program on this computer posts JSON to it
A GitHub, Linear or Telegram trigger	set up under connect
A new item in an RSS feed, a subreddit, a GitHub repository or a Hacker News search	checked every few minutes; each new item starts the flow once
An address answers something new	checked every few minutes
A file in the folder changes	changes made by flows themselves never count

The steps

Step	What it does	Uses a model?
Agent	A task for the crew, planned and reviewed like one typed in the chat	yes, a full run
AI	One answer: summarise, classify, translate, or pull out fields	yes, one call
If, Switch, Filter	Compare a field with a value and choose a branch, or stop	no
Merge	Wait for every wire into it and combine what arrived	no
Edit fields	Build an object from fields	no
Code	A few lines of JavaScript you write	no
Wait	A pause, up to an hour	no
HTTP request	Call any web API; paste a curl command or import an OpenAPI description	no
Services	Telegram, Discord, Slack, ntfy, email (Resend), GitHub, Notion, Todoist, Trello, RSS, Reddit, Hacker News, Wikipedia, weather, currency	no
App	One action of a connected service	no
Run a flow	Run another of your flows and use its result	no
File	Read, write or add to a file in the folder	no
Command	Run a command in the folder (waits for your OK in "ask" mode)	no

Every step can be switched off, retried up to three times, or told to carry on after an error. A flow can name another flow to run if it fails. Flows can be tagged, searched, duplicated, exported to a file and imported.

Credentials (bot tokens, webhook addresses, API keys) are kept apart from flows, encrypted, never sent back to the browser, and can be tested under more... -> Credentials. Exported flows leave them out.

Good to know

A flow can branch but never loop, and holds at most eight Agent and AI steps, so the model calls it can make are fixed by its drawing.
A flow runs only while Kadhai is open; missed schedules are not caught up.
Some settings never take data from the flow: web addresses and headers, commands, file names, repositories and recipients. Text arriving from outside can only fill in the parts meant for data.
App and service steps act without asking each time; choose actions that are safe to repeat.
The Code step runs your JavaScript in a separate worker with a 5-second and 64 MB limit. That contains mistakes; it is not protection against hostile code, so only use code you wrote or trust.
The keyless services (ntfy, RSS, Reddit, Hacker News, Wikipedia, weather, currency) were used for real; the services that need an account were checked to exist and to reject a wrong key, but have not been used with a real account yet.

This page comes from the user guide in the repository. Something unclear or wrong? Tell us.