# Review backends

Source: https://flow-next.dev/reference/review-backends/

The backend ladder, the backend:model:effort grammar, precedence, the host sentinel, and what the reviewer actually receives.

Every review gate runs through a configurable **review backend**, and the point of configuring one is that it is a *different* model than the one that wrote the artifact. The verdict grammar, receipts, fix loop, and optional `--deep` / `--validate` passes are identical across all of them, so pick the one your team already runs.

| Backend                        | Driver                             | Reviewer models                                                                                       | Shape                                                                                                          |
| ------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **OpenAI Codex** (`codex`)     | `codex` CLI                        | GPT family                                                                                            | headless, cross-platform                                                                                       |
| **GitHub Copilot** (`copilot`) | `copilot` CLI                      | several model families via a Copilot subscription (org-policy managed)                                | headless, cross-platform                                                                                       |
| **Cursor CLI** (`cursor`)      | `cursor-agent` CLI                 | several vendor families in one place - ask `cursor-agent --list-models` for the current ids           | headless subprocess; reviews billed against your existing Cursor subscription                                  |
| **Claude Code CLI** (`claude`) | `claude` CLI (`claude -p`)         | Claude family                                                                                         | headless subprocess, read-only by construction (three read tools, no shell); same family as a Claude Code host |
| **Host** (`host`)              | Host-native fresh-context subagent | Cross-family pin from the model-routing block in `CLAUDE.md` or `AGENTS.md` (never the session model) | **Bare only** - no subprocess; preferred from *inside* Cursor                                                  |

**Host** (`host`) is a model-less **selection sentinel**, not a CLI. Review runs as a host-native fresh-context subagent pinned to a model family that did **not** write the diff (pins live in the model-routing block of whichever instruction file holds it, `CLAUDE.md` or `AGENTS.md` - never on the backend string; `host:<model>` is rejected). Every re-review is a new subagent. Fail-closed: without a cross-family pin, interactive runs ask; autonomous runs stop with `NEEDS_HUMAN` rather than silent same-family self-review. Setup on Cursor leads the backend menu with Host (Recommended). On Grok, Host is also offered, but Grok’s only native model family is `grok-4.5` - native host review fails closed for a Grok writer unless the writer is non-Grok; cross-family review on Grok comes through bridge backends (`codex` / `cursor` / `copilot`). Muse Code is single-family too, so `host` fails closed there; use a CLI backend (`codex`, `copilot`, `cursor` or `claude`) in a Muse session started with `--disable-sandbox`, because the CLIs cannot write to their own home directories inside Muse’s sandbox. See [Orchestration → Cursor host](https://flow-next.dev/guides/model-routing/#cursor-host), [Install → Grok](https://flow-next.dev/install/#xai-grok-build) and [Install → Muse Code](https://flow-next.dev/install/#muse-code).

**Claude Code CLI** (`claude`) runs the Claude Code CLI headless with the prompt on standard input and exactly three tools (Read, Grep, Glob) with MCP servers excluded - there is no shell, because a pre-approved `git diff` would still accept flags that write files. The reviewed diff arrives as a file path under `.flow/tmp/claude-review/`, one file per reviewed range, so a re-review after a fix commit reads the new range while earlier evidence stays byte-identical. Sessions are resume-only: deep passes and validator passes continue the primary review by session id. The ladder steps on the CLI’s real model-unavailable signature (exit 0 with an error payload). On a Claude Code host this is a same-family second opinion, receipted rather than refused; independence is judged on the model family that wrote the diff, not on the host name.

**Cursor CLI** (`cursor-agent`) runs the same headless contract and verdict grammar as codex/copilot, with reviews billed against your Cursor subscription instead of a separate API key. It is **resume-only** (the first review persists Cursor’s `session_id`; re-reviews resume it) and **folds reasoning effort into the model name** (Cursor convention), so a spec is `cursor:<model>` with no `:effort` rung. From *inside* Cursor this path is circular - prefer `host`.

Set it once with `/flow-next:setup`, or override per run:

```bash
# persist the default (.flow/config.json)
flowctl config set review.backend codex
flowctl config set review.backend host          # preferred from inside Cursor


# override for a single run
/flow-next:impl-review fn-1 --review=codex|copilot|cursor|claude|host|none


# full spec form - backend:model:effort (host is bare only)
FLOW_REVIEW_BACKEND=codex:<model>:high
```

`none` is an explicit opt-out (skip review). The `:model:effort` suffix is optional and backend-specific. Codex and Copilot accept a `:model:effort` suffix (e.g. `copilot:<model>:high`); Claude Code CLI accepts `claude:<model>:<effort>` with the CLI’s own effort levels (`low`, `medium`, `high`, `xhigh`, `max`); Cursor CLI takes a model only (e.g. `cursor:<model>`) since effort is baked into the model name; **host** accepts no suffix at all. The chosen backend is recorded as the `mode` field on every [review receipt](https://flow-next.dev/reference/receipts/).

Every backend gives a change the same review. The **first** round runs one reviewer for a small diff in one area that touches no persisted or shared state, concurrency, security or data layout, and three reviewers (correctness, contracts, integration) for anything larger, merged into one fix pass. The re-review after fixes is one reviewer. The merged round counts as one round against the cap. It works the same from any harness, so flow-next in Codex with the `claude` backend takes the same steps as flow-next in Claude Code with `codex`. Switching backend changes which model reviews, and the panel stays the same. See [Three reviewers for risky diffs, one otherwise](https://flow-next.dev/guides/review-workflow/#the-first-round-draws-three-reviewers). How far the fix and re-review loop goes, attended or unattended, is in [Implementation review](https://flow-next.dev/guides/review-workflow/#implementation-review).

A per-task `review:` (or per-spec `default_review`) override routes end-to-end - it wins over the project default and env/config, so a task set to `review: cursor:...` under a `codex` project default actually reviews with cursor. Implementation reviews also carry an always-on **code-smell baseline** (Fowler *Refactoring* - Feature Envy, Data Clumps, Primitive Obsession, …) across every backend.

## Removed in 8.0.0: RepoPrompt

RepoPrompt support is gone: the `rp` backend, the Export Context skill and plan review’s `--review=export` mode. Reviews run on `codex`, `host`, `claude`, `copilot` or `cursor`.

A project that still names `rp` or `export` (in `review.backend`, `FLOW_REVIEW_BACKEND`, a spec’s or task’s review setting, or `--review=`) gets a one-line notice and continues with no reviewer configured, and `flowctl config set` refuses the value. Pick another reviewer:

```bash
flowctl config set review.backend codex        # or host, claude, copilot, cursor
flowctl spec set-backend fn-1 --review codex   # a spec that pinned rp
```

Re-run the Codex, OpenCode or Cursor installer to drop the Export Context skill from an existing install. Receipts already on disk with `mode: "rp"` still read.

**`review.backend` stays.** 7.1.0 said the setting would leave in 8.0.0 in favour of the model-routing block. It stays: the reviewer is chosen with `review.backend`, a spec’s or task’s review setting, or `--review=`, and nothing needs migrating.

## Managed review execution

A compatible host can run a configured review through a registered provider account. Flow-Next still prepares the review, records its findings and writes the ordinary receipt. This changes where the reviewer runs, not the selected backend or the workflow’s review rules.

The host supplies a session-scoped execution endpoint, token and launcher choice inside the agent session. Users do not need to set these environment variables themselves. A required managed review needs a Flow-Next installation that advertises managed-execution support; an older installation must be upgraded before that review can run. The host checks compatibility before its structured work, unattended (`flow --auto`) and review entrypoints. Ordinary direct chats remain available. Installing Flow-Next alone keeps the existing standalone CLI execution path.

When managed execution is configured, invalid scope, an unavailable provider or a malformed response stops the review. Flow-Next does not retry through an unscoped local CLI. The host decides which registered accounts and transports it supports; the hook does not make every backend available in every host. The CLI installation requirements below describe standalone execution; a managed caller does not need a separate reviewer CLI on its PATH.

For host implementers, the [execution-provider contract](https://github.com/gmickel/flow-next/blob/main/plugins/flow-next/docs/orchestration.md) documents the local protocol and capability probe. Local profile files are not part of that contract. Cloud execution and cloud credential handling remain host-specific work.

## Per-backend notes

| Backend   | Notes                                                                                                                                                                                                                                                                                                                                                              |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `codex`   | Codex CLI, cross-platform. Defaults to the strongest GPT tier the installed CLI accepts (the fallback ladder steps down automatically); tunable with `FLOW_CODEX_MODEL` and `FLOW_CODEX_EFFORT`.                                                                                                                                                                   |
| `copilot` | GitHub Copilot CLI, cross-platform. Read-only: it runs with write and shell tools denied, the same read-only tools the `claude` reviewer gets. Native Windows works from 1.1.9 via stdin delivery (below). Offers several model families via a Copilot subscription (org-policy managed).                                                                          |
| `cursor`  | Cursor CLI (`cursor-agent`), cross-platform. Model names carry their reasoning tier. Circular from inside Cursor, where `host` is preferred.                                                                                                                                                                                                                       |
| `claude`  | Claude Code CLI (`claude`), cross-platform; needs the CLI installed and authenticated. Read-only by construction, diff delivered by path, resume-only sessions. The cross-family pick from Codex, Cursor, Grok Build, Droid, OpenCode, or Muse Code; same-family (and receipted as such) on a Claude Code host, where `codex` or `host` keeps family independence. |
| `host`    | Host-native fresh-context subagent. Bare only; cross-family pin from the routing block; fail-closed `NEEDS_HUMAN` without a pin.                                                                                                                                                                                                                                   |
| `none`    | Skip review entirely, cleanly and visibly.                                                                                                                                                                                                                                                                                                                         |

### Windows + Copilot (1.1.9+)

Native Windows works. `run_copilot_exec` delivers the prompt via stdin on Windows (`subprocess.run(input=prompt, ...)`), sidestepping the `CreateProcessW` 32,767-char argv cap that broke the `-p` path for spec-sized prompts in 1.1.8 and earlier. Session continuity is tracked with a touch marker, because stdin-mode `--resume` is resume-only unlike `-p` mode’s create-or-resume. Verified by a real-subprocess Windows CI smoke. Upstream tracking: [github/copilot-cli#3398](https://github.com/github/copilot-cli/issues/3398).

## Precedence

Highest first: an explicit `--review=` argument → a per-task `review:` field or per-spec `default_review` → `FLOW_REVIEW_BACKEND` → `.flow/config.json` → backend env → the shipped default. A review skill with nothing configured anywhere hard-errors rather than silently skipping. Work and plan are the exception: they ask no setup question, run with review off, and say once in the handoff “no review backend set; run setup or set review\.backend”. Per-spec overrides are written with `flowctl spec set-backend`, per-task with `flowctl task set-backend`. A single task can pin its own reviewer and the override routes end-to-end, so a task set to `review: cursor:…` under a `codex` project default really does review with cursor.

```bash
flowctl config set review.maxIterations 6      # review-round cap (env MAX_REVIEW_ITERATIONS wins)
flowctl config set review.fanoutExecution sequential   # first-round reviewers one at a time (local models, rate limits)
```

Sequential fan-out is described in [Implementation review](https://flow-next.dev/guides/review-workflow/#one-reviewer-at-a-time-for-local-models-and-rate-limits).

The [model-routing tiers](https://flow-next.dev/guides/model-routing/#tiers-what-kind-of-model-a-job-wants) never touch this configuration. The reviewer tier is advice about *which family* to pick; `review.backend` is the machinery that runs it.

## What the reviewer actually receives (3.16.0)

The reviewer runs in your checkout with a shell, so it is handed **identities, not content**: the reviewed `base..head` range, the exact list of changed paths (`git diff --numstat --no-renames -z`, so nothing is elided, renames appear as real paths, and non-ASCII filenames survive), the repo-relative spec and task paths, and a few context hints. It reads the diff and the specs itself, at whatever depth each part warrants.

Earlier releases embedded the diff body in the prompt under a 50 KB cap, which meant a large change was reviewed against a truncated sample. Nothing is trimmed to fit now, and if a `git` read behind the evidence fails, the review stops with the underlying error **before** a review round is spent, rather than returning a verdict formed from nothing.

Re-reviews continue the reviewer’s own session, so when it checks whether your fixes landed it compares against findings it remembers making rather than a re-rendered list. When a session cannot be resumed, the prior findings travel in the prompt as before. On `codex`, a resumed re-review, validator pass, or deep pass is re-pinned to the model the prior receipt records, so it runs the model the review started with rather than the one in your Codex config.

Expect better-informed reviews rather than cheaper ones. A fetching reviewer spends turns on tool calls, so it is slower on a large diff and its measured token use went up, not down. The dispatch bound is 1800 seconds, overridable with `FLOW_REVIEW_EXEC_TIMEOUT`.

## Turning it off

`review.backend none` is an explicit opt-out, not a degraded mode. Every backend-driven review exits cleanly and the skip is recorded.

Under `flow --auto` the same rules hold. The unattended run resolves its backend from `--review=<backend>` (passed through unchanged to the `plan`, `plan-review`, and `work` dispatches; `qa` and `make-pr` take no review flag) or `flowctl review-backend`, records a `none` skip as `skipped(config: review=none)` on the stage line, and never lowers the gate or fabricates a verdict. A `host` backend with no cross-family pin stops the run with `NEEDS_HUMAN`, and a review that returns `NOT_RETRYABLE: artifact unchanged since last verdict` ends the run with `NEEDS_HUMAN` as well; both are human recoveries, never retries.