Flows

A flow gives one or more hosted agents defined roles in a task. Your working agent coordinates those participants, receives their results, and follows up across rounds. Use a flow when you want a separate reviewer or a repeatable collaboration between agents.

You need CLI setup and a connected daemon able to run the participant vendors. Participants use those vendors’ model resources or subscriptions.

Run a predefined flow

Predefined flows are named definitions in your workspace’s catalog. Capacitor includes code-review and spec-review; administrators can publish additional definitions for your team’s workflows.

Ask your agent for a flow by name, and describe the target and completion criteria:

Start a code-review flow for this branch, using Codex as the reviewer. Compare it with main and re-review after fixing findings.

Start a spec-review flow on this design document. Check the requirements and implementation risks, and iterate until the reviewer has no findings.

For a team definition, use its catalog ID:

Run the design-review flow on this proposal. Include the constraints we discussed and resolve the reviewer’s findings.

Give the agent the relevant document, intended behavior, and location of the changes. A request for a flow starts separate hosted participants. For questions about the recorded history behind a pull request, see PR review.

Work through a review

The reviewer reports findings; your working agent addresses them and asks for another round. A clean result means the reviewer has no remaining findings. Waiting or unclear needs attention, and failed needs investigation rather than being treated as sign-off.

You can request a reviewer from a different vendor than your working agent. Name a vendor and model if you have a preference. Otherwise, the catalog definition or your saved reviewer preference supplies the choice, and the agent asks when a choice is still needed. The selected daemon must support the requested vendor and model.

If the changes are uncommitted or live in another checkout, say so. A code reviewer can use the working agent’s checkout when available; open the run’s How it ran section to check the workspace it actually used. A fallback workspace may not contain your uncommitted changes. Ask the agent to supply the relevant diff or document when the review needs to rely on that context.

Flow runs and their results persist on the server. Ask your agent to continue the existing run when you return to the work.

Create or edit a reusable flow

Administrators use the flow editor at Administration → Flows → Flow Catalog (/admin/flows). In v1.1.1 this is a YAML editor with validation and version history.

1. Select a definition from Definitions, or choose New definition.
2. Edit the YAML to describe the participant roles, vendors and models, workspace access, and instructions for the first and subsequent rounds. Define the result criteria and execution limits the workflow needs.
3. Resolve validation errors, then choose Publish. Each publication creates a new version.
4. Make sure the definition is Enabled, then ask your agent to run it by its ID.

To return to an earlier definition, select it in Version history and publish its text as a new current version. Delete retires a definition; Restore makes it available to enable again.

Use the catalog for workflows you expect the team to run repeatedly. The Flow catalog reference explains the YAML format and provides an example.

Ask for a dynamic flow

A dynamic flow is defined for the current task instead of being published in the catalog. Ask your agent to create one when the work needs a specific combination of roles:

Run a dynamic flow to challenge this rollout plan. Use one participant for operational risks and another for test coverage. Give both the plan below, choose available models, and stop after at most three rounds.

Describe each role’s purpose, the context it should receive, and what counts as finished. Your agent prepares the definition and coordinates the participants.

Dynamic participants in v1.1.1 work from supplied context without a repository checkout. Include the relevant plan, diff, excerpts, or findings in the request. For a reusable workflow that needs repository access, have an administrator publish an appropriate catalog definition.

Dynamic flows must be enabled by an administrator. The server enforces limits on participants, simultaneous runs, rounds, spending, timeouts, and allowed models. The run’s Definition, as requested section shows what was requested; the server applies its configured limits. See Flows settings for the controls.

Follow a run in the web UI

Open Flows in the product sidebar with All Repositories or a repository selected. There is no project-scoped Flows view in v1.1.1.

In Runs, filter by status or search titles and targets, then open a run:

• Outcome shows each round’s result or failure reason. Expand earlier rounds to follow the changes.
• How it ran shows the definition and version, target, workspace, daemon, and links to the working and reviewer sessions.
• Participants shows each role’s vendor, model, state, estimated cost, and links to its agent and session. Stop is available for participants you are allowed to stop.
• Messages shows participant notes and their delivery state when messages were exchanged.

Use the working agent’s conversation to direct the flow and request follow-up work. The participant views let you inspect what each role did.

Compare reviewers

Switch to Reviewers and choose 7d, 30d, 90d, or All. The table groups completed-round metrics by reviewer model: runs, rounds, findings rate, rounds to clean, latency, and death rate. Sort by the measure you want to inspect and consider the sample size when comparing models.