Agentflows

Chain agents into a graph that runs on its own, with a person where it matters.

What an agentflow is

A graph you draw. Each node is an agent with a prompt, or an approval that waits for a person. Each edge is a condition: what the node before it ended with. Put a node that plans, one that builds, one that reviews, and an edge from review back to build for when it is not good enough, and you have a loop that runs on its own.

A run is one trip through the graph. It gets its own worktree and branch, every step is committed as a checkpoint, and you can watch it, answer it, take it over by hand, or rerun it from any node.

One piece of work, start to finish

1. An issue opens on GitHub and becomes a Task.
2. An agentflow picks it up. Its first node listens for task.created, so a run starts with the issue’s text as its first prompt, on a fresh worktree.
3. The agents work. A plan node writes a plan; the build node implements it; the review node either passes it or sends it back with what to fix. That back edge runs at most three times.
4. A person approves. An approval node stops the run and puts Approve and Reject on the node’s card. You get a notification, on your phone too if one is paired.
5. The PR opens, from the last node, or from the task’s Open a pull request button if you would rather.
6. You merge it from the Tasks page. The issue closes, and the task closes itself.

Any step can be yours instead. A flow with only some of these nodes is still a flow.

The Agentflows page

Agentflows at the top of the sidebar opens the page: a list of flows on the left and a canvas filling the rest.

• Each flow is a card with two buttons: the power button puts it Online or Offline, and the history button slides its runs open underneath. The second line says Online · <project> and when it last ran. Right-click a card to delete it.
• Click a card to edit the flow on the canvas; click a run to watch it on the same canvas.
• The inspector floats at the bottom right and follows what you select: the flow’s own settings, a node, or an edge. On a narrow window it folds into a pill.
• Editing does not autosave. The header has Save and Revert while there are changes, and Run once when there are none. Leaving the page throws unsaved changes away. A flow with unsaved changes cannot go Online or run, because a run uses what is saved, and that would not be what you are looking at.

Chat on the canvas toolbar opens a conversation with an agent that writes the flow for you. Describe what you want (it asks about the purpose, the entry, how to split the work, where it should run) and it builds the graph. That agent belongs to the flow: close the dialog and it waits, delete the flow and it goes too.

An agentflow only reacts to events and schedules when it is Online. New flows start Offline. Offline flows can still be run by hand.

Nodes

Agent: a prompt, which agent runs it, and optionally a model (empty means whatever that agent used last). It can declare outcomes, conclusions it may reach such as approved or needs-work, for edges to route on.

A node’s agent is a real agent, but its home is the run: it does not appear in the AGENTS list and does not open a tab. Its permission requests are approved automatically, since nobody is watching it; this is the one place Kumo approves anything, and it is the node that decides, not the mode. Questions and plan reviews still stop it as stuck, until you answer.

Approval: waits for a person. Emits approved or rejected.

Edges

An edge says when the next node runs:

Several edges into one node mean any of them starts it. Routing happens when a node’s turn ends, not while it runs: everything it emitted during its turn is collected and passed over the edges in one go.

A back edge points at a node earlier in the chain. It sends that node another round with its context intact, and has a budget, three rounds by default; when it runs out, exhausted lets another edge catch it.

How a run starts

An entry node is one with no forward edges into it. A run can start four ways:

• By hand: Run once in the header. It starts every entry node.
• On a schedule: a cron line on an entry node.
• On an event: an entry node listening for a topic. task.created, task.updated, task.done and task.deleted come from Tasks, and task.updated can be narrowed to a stage (start when a task reaches ready) or to what changed. GitHub events (github.issue.opened, github.pr.merged…) and anything an agent emitted work too. A flow only hears events from its own project.
• From a task: Run flow ▾ on the Tasks page or the Task panel. This works Offline too, since you pressed it.

One task, one run. If this flow already has a live run for a task, another event for the same task waits and is reconsidered when that run ends, rather than piling a second run on top. Run flow says That task is already running in this flow.

A run started by a task runs on the task’s Workspace if it has one, and otherwise on a new one under the task.

Where a run works

Set in the flow’s own settings:

• Worktree (the usual): each run gets a new worktree and branch, kumo/run-<id>.
• Fixed directory: every run works in one folder you choose, one at a time. For flows that are not about a repository at all, a managed project is a good home.

Up to three runs of one flow go at once by default; the rest queue. A run can execute at most 50 nodes in total; beyond that a node shows blocked rather than quietly disappearing.

Fan-out and join

If a node emits several matching results on one edge (say, a triage node that finds three bugs), the run fans out: each result gets its own chain on its own worktree branch, and the next node runs once per chain. Node cards show ×3 and a line like 2 done · 1 running.

Select a node and the inspector lists its executions per chain: status, why it is blocked, and Approve / Reject, Cancel and Rerun for each. Cancelling one chain leaves the others running. An edge on joined waits for the whole fan-out and receives every chain’s result.

For work that really is separate, prefer making separate tasks (kumo task new) so each one gets its own run.

Watching a run

Click a run in the history. The running node breathes on the canvas, and the edge into it pulses. With nothing selected, the inspector is the run’s timeline, node by node. Select a node to read its conversation; if it is stuck, answer it right there and it carries on. Approval nodes grow their buttons on the card. Cancel run is in the header while it runs.

A node that fails with an on: failed edge is handled. One that fails with nobody to catch it fails the run and sends a notification. stuck is not a failure.

Checkpoints and rerunning

A run copies the flow when it starts, so editing the flow afterwards never changes a run in flight. Every node’s turn ends with a commit, [kumo] checkpoint after <node>, so you can Rerun from a node…: the folder is reset to that node’s starting commit and the run carries on from there. A run that is still going reruns that chain in place.

A run that produced no checkpoint and left a clean tree takes its worktree and branch with it when it ends, so a flow that checks something every half hour does not fill ~/worktrees.

Taking over by hand

When a run is stuck, or you want to do the next bit yourself, Open in project on the run page turns the run’s folder into an ordinary Workspace on the tree. Nothing is copied. The board grows a banner saying which flow and run this is and what state it is in, with Reply › when a node is waiting on you; while the run is still going, your edits land in its next checkpoint.

From then on the folder is yours. Kumo will not sweep it away when the run ends, and Rerun from a node… refuses to reset it while it has uncommitted changes.

Agents you start there are ordinary agents. They can run kumo run to see which flow and run the folder belongs to, which node is stuck, and what each step did.

For agents

kumo emit <topic> sends an event a flow can listen for. kumo flow list / get / put reads and writes flow definitions (that is how the Chat agent builds one). kumo run prints the run the current folder belongs to. See Agents working together.