Skip to content

How a flow works

Milimarty edited this page Oct 19, 2026 · 2 revisions

How a flow works

 you: "show each player's rank"
   │
   ▼
 spec ─◆─ red ─ green ─◆─ … (one loop per criterion) … ─ review ─◆─ done
        │     │       │                                          │
        │     │       └ you approve each criterion               └ you approve the end
        │     └ an agent writes the smallest code that passes; keel commits it
        └ you approve the criteria; an agent writes a failing test, keel checks it fails, then commits it
  • The flow is a LangGraph graph; the agents are LangChain or CLI agents.
  • keel runs the tests and makes the commits itself, on its own branch (feat/…). It never pushes, and it never commits files you changed yourself.
  • keel's commits are by you, and end with Co-Authored-By: KeelBot <keel.dev.bot@gmail.com>, so GitHub shows both. Settings › Git: KeelBot as co-author (on by default) and Commit author (Name <email>; empty: the project's git name — in Docker there is none, so set it there, or the commits are by KeelBot alone).
  • Every step, file change, command and token is visible: Live agents, Jobs, Budget. A code step (the setup ladder, a test suite, a commit) is a job too: agent "keel", no model, no tokens. The Flow page shows the line it is at ("rung 4/12 · Both apps compile: $ npm run build"), then "passed" or "failed (exit 1)".
  • The Flow page (0.18.11): each block shows what really ran (model and effort, time, cost, the first line of its answer, ×N tries). Phases fold to one line with a summary. The criterion loop has one row per criterion with its tries and why you sent it back. Needs you is pinned on top. The canvas follows the live step until you scroll (Jump to live brings it back). A gate card says what you approve, the cost so far, the proof, and what happens after Approve and after Send back; in the card A approves and R opens the reason box.
  • Choices are cards (0.18.13): every gate with named choices shows one card per choice, with what it does, which one a plain approve takes, and whether it needs a reason. Keys 1–9 pick. A question can take several answers (tick each that applies).
  • A stuck criterion gets a ladder: the same agent with the exact failure → a different agent (investigator) → a stronger model once → you, with real choices (retry with a note, skip, edit the spec, stop). After 5 send-backs or retries in a row keel asks "go on anyway / stop". A test command that cannot start is said plainly. "No tests found" is never green.
  • The spec's build order: when a spec says **ORDER**: AC-6, AC-2, …, keel builds the criteria in that order. An amendment that changed nothing never loops: you get build another criterion first, skip this one for now, edit the spec or stop.
  • Several flows at once: while a flow runs in the project folder, the next one runs in a worktree of its own (a copy of the project on its own branch, under .keel/worktrees/), so neither touches the other's files. Press Start on three tasks, or Start another flow on the Flow page. The Flow page then shows a board: each flow, the files two flows both change, the branches that will not merge cleanly, and an order to merge them in. The Inbox groups their gates by flow. On top of the Flow page, a tab for each flow that runs or waits switches between them, and History lists every flow of the project (all, or one workflow's); Open shows any of them with all its details.
  • When something needs you, keel plays a sound, shows a pop-up and its mascot jumps.
  • keel v2 has its own guard, rules, agents, skills and MCP server. keel v1 is a separate project and is not in the image.

From docs/GUIDE.md · All pages

Clone this wiki locally