Flows

Surfaces: your agent (start and drive a flow) · web app (Flows: runs and reviewers) · administration (the catalog)

The web app is at https://<your-workspace>.kcap.ai for a cloud workspace; on the local edition the same pages are served from your machine. The desktop app opens it from Help and support → Open dashboard, and kcap local open opens the local one from a terminal

A flow gives one or more hosted agents a defined role in a task and runs them in rounds. The common case is a review: your working agent submits work, a separate reviewer reports findings, your agent fixes them and submits again, until the reviewer has nothing left. Flows need a daemon that can run the participants’ vendors; each participant uses that vendor’s own subscription or keys

What you can do

Run a flow from the catalog. Your workspace has code-review and spec-review built in, and admins can publish more. Ask your agent which flows exist, then ask for one by name with the target and the finish line:

Start a code-review flow for this branch against main, using Codex as the reviewer. Fix the findings and re-review until clean

Run the spec-review flow on this document. Iterate until the reviewer has no findings

Name a vendor and model if you have a preference; otherwise the definition or your saved reviewer preference (kcap config set flows.reviewer_vendor codex) decides, and the agent asks when it still needs a choice

Ask for a one-off flow. When no definition fits, describe the roles and let the agent build the definition:

Run a dynamic flow to challenge this rollout plan: one participant for operational risk, one for test coverage. Give both the plan below and stop after three rounds

Dynamic participants work from the context you supply, without a repository checkout, so include the plan, diff or excerpts. Admins decide whether dynamic flows are allowed and cap participants, rounds, spend and timeouts; the run’s Definition, as requested section shows what you asked for and what the server applied

Follow a run in the web app. Flows in the sidebar, with All repositories or a repository selected, lists runs by status. Open one:

• Outcome: each round’s result (clean, findings, waiting, unclear, failed) and the findings themselves
• How it ran: definition and version, target, workspace, daemon, and links to the working and reviewer sessions
• Participants: each role’s vendor, model, state and estimated cost, with Stop where you are allowed
• Messages: notes between participants and their delivery state

A round can outlast your agent’s tool call; the agent is told the run is still going and checks back. If it loses the run id, it reads the newest open flow this session started

Compare reviewers. The Reviewers tab groups completed rounds by reviewer model over 7, 30 or 90 days: runs, rounds, findings rate, rounds to clean, latency and failure rate. Small samples mislead; read the counts before the rates

Write a flow definition for your team. Admins publish definitions in Administration → Flows → Flow Catalog as YAML with validation and version history. You do not have to write the YAML by hand: describe the roles, the rounds and the finish line to your agent and it drafts the definition for an admin to paste in and publish. A definition has an id, a description the agent reads when choosing, and either one reviewer with top-level rounds or several participants each with their own. Every role needs an initial_prompt and a follow_up_prompt; add *_context_only variants for reviews that run without a checkout. rounds.result names the markers that mean findings and clean; limits caps rounds, timeouts, idle time and spend

id: design-review
description: "Review a design document for missing requirements and implementation risks."
reviewer:
  workspace: mirror-requester
rounds:
  initial_prompt: |-
    Review the submitted design for missing requirements and implementation risks.
    Read the relevant repository files to verify its assumptions.
  follow_up_prompt: |-
    Review the updated design and report unresolved or new findings.
  initial_prompt_context_only: |-
    Review the submitted design using only the supplied context.
    State which assumptions you could not verify without repository access.
  follow_up_prompt_context_only: |-
    Review the updated design using only the supplied context.
  result:
    findings_marker: "FINDINGS:"
    clean_marker: "NO FINDINGS"

Leaving vendor and model out of a single-reviewer definition lets the person starting it choose. Publish creates a new version; the Enabled switch decides whether agents can start it

Help me get unstuck

The agent says it cannot find a flow. The definition is disabled or deleted. Admins restore it in the catalog

The reviewer did not see my changes. They were uncommitted or in another checkout. Commit, or tell the agent to pass a diff; How it ran shows which workspace the reviewer used

A round came back failed. The reviewer did not finish: a crash, a timeout, a vendor error. Read its session, fix the cause, and ask for another round. Failed is never a sign-off

The flow seems stuck. Ask your agent to check the flow’s status; without the id it reads the newest open run from this session or, on agents that do not identify their session to kcap, from this repository on this machine

My reviewer was reaped for silence. Unattended reviewers are reaped when they stop producing output, not for taking long. Read the reviewer’s session to see where it went quiet, then ask for another round

The daemon refused to launch the reviewer. Each reviewer vendor is verified at a particular build, and the daemon refuses an installed build older than that. Update the vendor’s CLI on the daemon’s machine; if the installed build is the one you want to run, kcap daemon reviewer affirm --vendor pi records it as the new floor