Flows

A flow is a fixed recipe Toby follows step by step: gather information from your apps, optionally use AI to summarize or decide, run actions, then deliver the result. Unlike a chat, a flow does the same thing the same way every time, so it suits routines you run often.

Use a flow when you want:

• A one-click button on Home. For example, "Focus mode" turns off Wi‑Fi and minimizes every window.
• A live card on Home. For example, "Top Jira issues assigned to me", refreshed whenever you open Toby.
• A result sent somewhere. For example, a daily task digest emailed to you or posted to Slack, run by a schedule trigger.

The built-in Upcoming, Tasks, and Unread mail cards on Home are flows too.

Build a flow from a description

Ask Toby in chat, for example: “Create a Home action that summarizes my upcoming calendar events.” The built-in flow-builder skill checks available tools, collects any required details, and saves a custom flow. Open Flows to review or run it. Home actions also appear in the Actions rail.

Saving does not run the flow. Each step shows the settings it needs; optional settings you haven’t filled in sit under More options. To use a value from the trigger or an earlier step instead of typing one, click the link button beside a field and pick it, for example The new file from a file trigger or AI answer from an AI prompt above it. Use a field from it… picks a named field such as title. To run a tool with an AI answer, click Add an action after the AI prompt. For a notification, keep the title typed and link the description to AI answer. For file triggers, see Event automations. Click a step’s title to collapse it to a one-line summary. For a new AppleScript or TypeScript step, Toby can draft the code and guide you through saving it in Script Tools before adding it to the flow.

Actions normally run every time the flow reaches them. Choose Only run when… from an action’s ••• menu to run it only when a previous output field is boolean true. A false value skips the action; a missing field or another type stops the flow before it calls the tool. Skipped actions appear in run history with their reason.

Notify only when a meeting is coming

1. Click Add an action and add the calendar Upcoming events summary. Its output includes a generatedAt timestamp for the current time.
2. Click Add an AI prompt, then choose Answer format → Named fields. Add shouldNotify (Boolean), title (Text), and description (Text).
3. Ask AI to compare meeting start times against generatedAt and set shouldNotify to true only for meetings starting in the next ten minutes, ignore all-day and ongoing events, and write the notification title and body. It must fill every field even when no notification is needed.
4. Click Add an action and add Show notification below the AI prompt. Link title and description to AI answer with the link button, then choose Use a field from it… and enter title and description.
5. Choose Only run when… from the action’s ••• menu, select that same AI output, and enter shouldNotify.
6. Save the flow and schedule it at 25,55 * * * * for :25 and :55 each hour.

Completion notifications are optional per trigger. Leave Notify me when it finishes off for quiet checks.

Named fields support text, boolean, and number values. Names must start with a letter and use letters, numbers, and underscores; each field needs a unique name. All fields are required. Toby validates AI output before it reaches an action.

Conditions apply to actions. The Shares destinations still run after a successful flow; use a conditional send action for email or Slack delivery that should depend on the decision. The Mac must be awake, the daemon running, and calendar and notification permissions enabled.

Changing a flow's destination to a dashboard card preserves its existing steps and the data passed to its LLM prompt. Refreshing the card runs the saved flow.

What flows are for

Piece	Role
Local tools	Read or act on connected services (unread mail, open tasks, upcoming events, and so on)
Persona	Supplies the model, tone, and priorities for any LLM step
LLM step	Turns tool results into prose or structured output (for example a markdown summary)

Unlike chat, a flow does not improvise a multi-step tool loop. It runs a defined sequence of steps so the same job behaves consistently every time.

Built-in flows (dashboard)

The flows that ship with Toby are built-in and power the Home cards:

Dashboard block	What the built-in flow does
Email	Loads unread-style email items from your email integration, then summarizes them for the card
Tasks	Loads open tasks, then summarizes what needs attention
Calendar	Loads upcoming events, then summarizes what’s coming up

Those pipelines use the Home persona (configured under Settings → Home) for their model and writing style. Connect the matching integrations, leave Toby running, and Home can refresh those blurbs automatically.

Their When section shows Home refresh. Home runs these flows when it needs a fresh summary or you explicitly refresh the card. Fresh cached summaries are reused for up to five minutes; a previous summary can stay visible while a replacement is generated. Empty cards skip the flow. Built-in flows remain read-only. For custom flows, choosing Home refresh automatically selects Show it on Home → A card with the answer and makes that location required. You can change its color and automatic/manual update setting. Disabling the trigger pauses updates; removing it removes the Home card. Choosing Home Screen Action instead switches to an Actions button.

Browse flows in Toby.app

Open Toby.app and choose Flows from the sidebar (or the View menu / menu bar).

Use Filter flows to show All, Manual, Home Actions, Home Refresh, Scheduled, or Events. Home Refresh includes built-in and custom flows that update Home cards, including flows whose refresh trigger is disabled.

From there you can:

• See all flows in the workspace list (nothing is selected until you choose one)
• Select a flow to open its page, or click empty space in the list to clear the selection
• On Details, inspect description, steps (tool + model nodes), metadata, and finish destinations
• Switch to Recent runs for history, and open a run for status, timing, and per-step detail

Built-in flows are labeled and are read-only in the UI.

Create your own flow

Click + in the Flows toolbar. The New flow sheet walks you through the flow’s steps (actions and AI prompts, in any order) and where the answer is shared. Nothing is created until you click Save.

When you replace a step, Toby keeps a selected result if its output still exists. If that output was removed, the flow uses the new final step’s result automatically.

1. Name and look. Give the flow a name and a one-line description, then pick an icon and color under Look. The color is used for its Home button (teal if you skip it).

2. Steps. Steps run from top to bottom, and each can use the output of any step above it. Mix the two kinds freely:

   • Add an action reads from or acts on your apps (tasks, calendar, mail, macOS controls, or your own script tools). Fill in any settings a step needs, such as Wi‑Fi on or off, when you add it. Choose Only run when… in its ••• menu when it depends on a boolean decision.
   • Add an AI prompt describes what the AI should do with earlier results, for example "List the three most urgent items in one line each." A flow can have several AI prompts; a later one can read an earlier one’s answer.

   Reorder steps by dragging them or with Move up and Move down in the ••• menu.

3. Shares. Choose where the result goes. Show it in a window is the default. You can add or swap in:

   • Email or Slack (that app must be connected)
   • Home, as either:
     • A card that shows the latest result. As Needed (default) refreshes it when you open Home and the last run is more than a few minutes old. Manual refreshes only when you click refresh.
     • A button in the Actions strip that runs the flow when you click it. Hover over a button to see its name and description.

4. Click Save, then Run now to try it.

You can combine a dashboard card with a result window (or email / Slack). A flow can have only one Dashboard destination. Email and Slack still send when you Run now or when a schedule fires — not when the home card refreshes.

A good first flow is a focus macro: turn Wi-Fi off, then minimize all windows. Use Previous step output to pass data or IDs from a source into another tool. Named AI fields can supply a single text ID; AI-selected lists of IDs still need chat or an Agent Task step because structured flow output does not yet support arrays.

To run on a timetable, add On a schedule in the Flow editor’s When section. See Scheduled flows.

Home color

In a flow's dashboard output settings, use Home color to choose the default appearance of its Home card or Actions tile. The palette includes teal, blue, green, orange, purple, pink, red, and gray. Neutral removes color; Automatic keeps the existing appearance (neutral cards, or the flow color for Actions tiles).

Colored cards have a border in the selected color and a subtle background tint that adapts to light and dark mode. Save the flow to apply its default. You can choose a different color for that block through Edit Home; that override is saved only on this Mac. Choose Use default there to follow the flow again.

Reuse a script in several flows

Open Script Tools from the Flows list, then choose New Tool. Give the tool a name, choose TypeScript or AppleScript, add a named row for each string input, and choose text or JSON output. The code editor shows line numbers and colors TypeScript and AppleScript syntax. Enter example values in the matching Test inputs fields and choose Run Test at any time, including before saving a new tool or edits. Testing does not save changes. Choose Save Tool when you're ready to make the script available to flows. In a flow's Add tool picker, your scripts appear under My Tools.

To draft or revise a script with AI, choose Edit with AI above the editor. Describe what to build, then enter follow-up requests such as “add an error message when the input is empty.” Each request uses the latest editor code, tool settings, and recent requests as context. Toby replaces the editor code with the result, so review it before you test or save. You can edit the code yourself between requests. The request history lasts only while this tool is open in the editor. AI editing supports code up to 20,000 characters. AI edits do not run or save the script.

TypeScript tools export a default async function that receives an object of named inputs and returns the output. AppleScript tools use on run argv; the inputs arrive as strings in the order you listed them. For JSON output, AppleScript must return a JSON string. Editing a saved script changes what all flows using it run. The library shows how many flows use each tool, and it won't delete a tool while a flow references it. Scripts run with your macOS user permissions, so review code before saving and testing it.

Advanced

Use step data in an AI step

Tool steps show the reference you can copy into a prompt. The LLM step's Insert step output menu inserts one for you. For example, {{json bag.jiraIssues}} includes the Jira data when a step saves its output as jiraIssues. The reference uses the saved output name, which can differ from the step's name. When multiple steps share a reference, the last step's data is used.

To inspect the actual data, open a flow's Recent runs, select a run, and expand the step's Outputs under Nodes. The Jira search output includes an issues array. An LLM output saved as summary is displayed from summary.markdown; flow creation now checks that the requested result exists in the step outputs.

Home Screen Action

Choose Home Screen Action in When to add a button to Home’s Actions. Toby automatically selects Show it on Home → A button in Actions in Where it shows. That location cannot be removed or switched to a card while the trigger exists; you can still change its color and add other destinations. Choosing A button in Actions first also adds the matching trigger.

Change or remove the Home Screen Action trigger to unlock the location. It becomes a Home card that you can then change or remove. Disabling the trigger hides its button, while keeping the required location saved.

Keep a Manually trigger as well if you want Run Now from Flows. The Home button and Run Now can have separate trigger inputs, and both appear in the same run history.

When a Flow runs

Flows combine steps and triggers in one place. New flows start with an enabled Manually trigger for Run Now. Add Home refresh, Home Screen Action, schedule, wake, return-after-idle, or file-change triggers in When. Each has its own inputs, conditions, limits, and optional completion notification. Automatic triggers start disabled; enable them when you are ready for future runs. Keep a manual trigger to run on demand.

Use the All, Manual, Home Actions, Scheduled, and Events filters to find flows. Trigger activity shows runs and skipped events, with links to detailed traces. All trigger types share the Flow's steps, persona, result, and destinations.

Choose Agent Task — can use tools for a prompt that needs Toby to choose its own tools, use skills/memory, or work in a project. Choose Generate an answer for fixed markdown or named-field output from supplied data. A flow can have several AI prompts, and they share the flow’s persona. Agent Tasks cannot ask questions while running.

Chat remains the interactive option for open-ended work and follow-up questions.

Tips

• Connect Email, tasks, and Calendar integrations so dashboard flows have something useful to summarize.
• Tune Settings → Home for the persona used by Home AI blurbs.
• Use the Flows window when you want to see why a dashboard blurb looks the way it does (which tools ran, and recent history).
• For a first custom flow, start with tools whose arguments you already know (Wi-Fi off, volume, minimize all). Leave “pick these emails and archive them” to chat.

Related

• Toby.app — Home, Flows window, and settings
• Personas — Model and instructions used by LLM steps
• Schedules — Run a prompt or a flow on a timetable
• Integrations — Local tools flows call

Run on a macOS event

Add an event trigger in the Flow editor. Toby.app must remain running to observe wake, idle, or file-change events.