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 Codex reviewer the server spins up on one of your daemons to do the actual reviewing.

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 Codex reviewer

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 Codex agent, so at least one daemon must be reachable by your server. For a code review that reads the repo directly, that daemon needs the repo checked out; 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 Codex reviewer the daemon launches is provisioned automatically — its worktree is pre-trusted and it’s handed exactly one MCP tool, the result-submission tool it uses to report findings (it can’t start a nested flow). You never configure the reviewer side.

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

The review loop

Start a flow against a spec or a change. The server launches a Codex reviewer and returns a flow_run_id plus the first round’s result.
If the result is findings, address them in your session.
Submit a round with the updated context. The same reviewer re-reads and responds.
Repeat until the reviewer returns no findings — that’s the sign-off.
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`
`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. If the reviewer’s daemon has the exact same repo checked out, it can read the working tree directly; otherwise start the flow with mode: "context-only" and the diff/context you submit is treated as authoritative. Starting a code review without an exact repo match and without 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.)

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) Codex agent 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.

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