Review flows

A review flow is an iterative review loop that a coding agent runs from inside its own session: it hands a spec or a code change to a Capacitor-hosted reviewer, gets back findings, fixes them, submits another round, and repeats until the reviewer signs off. It’s the machinery behind the kcap:review-flows skill.

Two pieces make it work: the kcap mcp flows MCP server, which exposes four tools the agent calls, and a hosted reviewer — a vendor you choose — that the server spins up on one of your daemons to do the actual reviewing. The reviewer vendor is picked independently of the agent driving the flow (see Choosing your reviewer).

Not the same as kcap review

Review flows are distinct from kcap review <pr-url>:

	kcap review	Review flows
Kicked off by	a person (or CI)	the agent, mid-session
Target	a merged/open GitHub PR	a spec, branch, file, or diff
Shape	one-shot Q&A over transcripts	multi-round findings → fix → re-review → sign-off
Runs in	Claude Code	a hosted reviewer you choose

Use kcap review to interrogate the sessions behind a PR. Use a review flow when you want an agent’s work checked, fixed, and re-checked before it’s considered done.

Prerequisites

• kcap login on the host — the flows server authenticates as you.
• A connected daemon (see Hosted agents). The reviewer runs as a hosted agent, so at least one daemon must be reachable by your server and must have the chosen reviewer vendor’s CLI installed. For a code review, the reviewer reads your working tree directly when the daemon can reach it; otherwise pass the diff as context (see context-only below).

Register the MCP server

Registration is part of setup — you rarely touch it by hand.

Claude Code (the driver). kcap setup installs the kcap plugin, which auto-registers kcap-flows via its .mcp.json — with the server’s working directory pinned to your project, so it already resolves to the repo you have open. There’s nothing to add. Verify with claude mcp list (look for kcap-flows … ✔ Connected); reload the repo if you just ran setup, since MCP servers load at session start.

Codex (the driver). kcap-flows is deliberately not auto-registered for Codex — it launches a paid hosted reviewer, so you opt in by hand. Add it to ~/.codex/config.toml:

[mcp_servers.kcap-flows]
command = "kcap"          # desktop app has no shell PATH — use an absolute path, e.g. /opt/homebrew/bin/kcap
args    = ["mcp", "flows"]

Restart Codex afterward.

The reviewer needs no setup. The hosted reviewer the daemon launches is provisioned automatically — it runs unattended, pre-trusted, and is handed only a minimal result-submission surface for reporting its verdict; crucially, it has no kcap mcp flows tools, so it can’t start a nested flow. It also auto-approves its own read-only kcap tool calls so a round never stalls on a permission prompt. You never configure the reviewer side.

Registering Claude Code by hand, if you ever need to

Add it at user scope so it applies in every repo: claude mcp add -s user kcap-flows -- kcap mcp flows. A user-scope entry inherits whatever repo you’ve opened as its working directory — which the flows server resolves to a repo (working directory → git root) — so that’s what you want; a project/local entry pinned to a parent folder won’t work.

The kcap:review-flows skill drives these tools for you once the server is registered.

The review loop

1. Start a flow against a spec or a change. The server launches the reviewer and returns a flow_run_id plus the first round’s result.
2. If the result is findings, address them in your session.
3. Submit a round with the updated context. The same reviewer re-reads and responds.
4. Repeat until the reviewer returns no findings — that’s the sign-off.
5. Close the flow.

Each call is a long poll: the reviewer takes up to a few minutes per round, and the tool waits for its verdict rather than returning immediately.

The four tools

Every tool after start_review_flow takes the flow_run_id it returned.

Tool	Purpose	Key arguments
start_review_flow	Open a flow and run round 1.	kind (spec-review | code-review), target_kind, target_ref, target_title, context; optional instructions, mode, vendor, model
submit_review_round	Re-review after you’ve addressed findings.	flow_run_id, context; optional instructions
get_review_flow_status	Check state without submitting.	flow_run_id — returns status, round count, and the last result
close_review_flow	Stop the reviewer and mark the flow closed.	flow_run_id

A reviewer verdict is one of: findings (issues to fix), clean (no findings — the sign-off), waiting, or unclear. A flow run can separately end in a failed state if the reviewer can’t complete.

spec-review vs code-review

Two flow kinds ship:

• spec-review — review a spec or design document. The content you’re reviewing travels in context.
• code-review — review a branch, PR, or diff. By default the reviewer borrows your working tree: it runs read-only in your live checkout, so it sees uncommitted, untracked, and gitignored files, and re-reads them on every round. When the daemon can’t reach that checkout, start the flow with mode: "context-only" and the diff/context you submit is treated as authoritative instead. Starting a code review with neither a reachable working tree nor context-only is rejected, so you always get one or the other. (The reviewer is told not to run tests — CI covers that; feedback is on the code.)

Choosing your reviewer

The reviewer vendor is a choice you make per flow, independent of the agent driving it — a Claude session can request a Cursor reviewer, a Codex session can request Claude, and so on. Pass the lowercase vendor token as vendor on start_review_flow; if you name a reviewer in your request (“start a review flow with Cursor”), the skill maps it for you. Naming a reviewer is never inferred from the driver. The request succeeds only if one of your connected daemons can host that vendor unattended.

Reviewer	Vendor token	Notes
Claude Code	claude	Reviews in a daemon worktree.
Codex	codex	Can borrow your checkout under an OS read-only sandbox.
Cursor	cursor	Can borrow your checkout via a materialized snapshot.
GitHub Copilot	copilot	Can borrow your checkout via a sandboxed snapshot.
Gemini CLI	gemini	Worktree or context-only.
Kiro	kiro	Worktree or context-only.
OpenCode	opencode	Read-only tool surface — give it context or a file-based diff.
Antigravity	antigravity	Worktree or context-only. (agy is the binary — the reviewer vendor token is antigravity.)
Pi	pi	Worktree or context-only.

• If you don’t name a reviewer, the flow uses the definition’s authored vendor, or your saved preference — the skill remembers your last choice. With none of those the server asks you to pick; nothing is silently chosen.
• Model override. Add model (which requires vendor) to pin the reviewer’s exact model, e.g. vendor: "claude", model: "claude-opus-4". This rolls out per daemon — where the daemon doesn’t yet advertise a model resolver for that vendor, the reviewer runs on the vendor’s default model. Don’t pass default or auto as a model value; omit model to get the default.

The skill

The bundled kcap:review-flows skill teaches an agent when and how to run the loop — start against the right target, submit rounds as it fixes findings, and only close after a clean verdict. Install it with your agent skills (kcap plugin install --skills; see Setup CLI).

Once it’s registered you don’t call the tools by hand — but you do have to ask for a flow explicitly. A bare “review this spec” or “review my PR” makes the agent review the work itself, in your session; to hand it off to the separate reviewer, name the flow (or the independent reviewer):

“Start a review flow on this spec.” · “Get an independent review of this branch.” · “Re-review — I addressed the findings.”

The reviewer is a real, hosted (paid) agent — the vendor you choose (see Choosing your reviewer) — that consumes compute/tokens. It’s inert until a daemon exists, so nothing runs by accident — but it isn’t free once it does.

Durability

A flow is durable. Its state — every round, its context, and the reviewer’s verdicts — is event-sourced on the server, so a flow survives a server or agent restart. Hand a flow_run_id to get_review_flow_status later and you get the full history back; resume by submitting the next round against the same id.

Related

• PR review — the one-shot kcap review <pr-url> command, and how it differs.
• Hosted agents — the daemon that hosts the reviewer.
• Setup CLI — kcap login and installing agent skills.
• Commands — the kcap mcp flows entry in the CLI reference.